{"id":1062,"date":"2017-09-26T10:52:37","date_gmt":"2017-09-26T14:52:37","guid":{"rendered":"https:\/\/blogs.mathworks.com\/developer\/?p=1062"},"modified":"2017-09-29T00:05:23","modified_gmt":"2017-09-29T04:05:23","slug":"the-build-matrix-laboratory","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/developer\/2017\/09\/26\/the-build-matrix-laboratory\/","title":{"rendered":"The (Build) Matrix Laboratory"},"content":{"rendered":"

Ah the joys of a new release! R2017b<\/a> is now out and packed with some great new features. So here I go, heading out to an excitement fueled upgrade-mania when lo and behold, my glee is rudely interrupted when I see my code is broken in the new release.<\/p>

What a drain on an otherwise pleasant experience! It turns out that the error is due to some of my more \"creative\" and \"clever\" coding practices that have helped me get my job done in the past, and when I dig in I see that I've been warned about this change coming for years. The problem is I never seem to have the time to comb the release notes as much as I'd like to, and even if I did realizing that my code I wrote 5 years ago has some of the problems mentioned is a tall order.<\/p>

To compound that, even though I'd like to upgrade, when I make the needed adjustments to do so I worry about breaking the users of my code who haven't upgraded yet.<\/p>

What in the world to do?<\/p>

Let's use some continuous integration! Last I checked we were still in charge of the machines so let's put them to good use. It is actually quite easy to put this into practice using Jenkins. Jenkins supports<\/a> what is known as matrix builds so that we can ensure our code works across many different MATLAB releases. To set this up, simply create your project as a Multi-Configuration Project in Jenkins.<\/p>

\"\" <\/p>

Once this project is created we get the opportunity to define our own configuration matrix. This means that we can add an axis of configuration where we can define a particular system property (i.e. environment variable) as well as the different values we'd like to have for each of these values. What I want to do is add the MATLAB version and point it to several releases I'd like to test against, like so:<\/p>

\"\" <\/p>

Once this is done, Jenkins will create multiple configurations for our build and it will be parameterized across this value. So, as we set up the build step (which we would set up to run our tests against thecode changes) this value can be leveraged in the build script to ensure this happens on all the releases. For example, our build script can point to the different installation locations of the different MATLAB releases I want to test against:<\/p>

\"\" <\/p>

Simple as that! What does this give us? It gives us a new build configuration (which really feels like a new build) for every value of MATLAB_VERSION<\/tt>. To see how this can help, let's look at a quick example. Here we have a bit of source code simulating a mass spring damper...<\/p>

\r\nfunction<\/span> [x, t] = simulateSystem\r\n\r\nspringMassDamperDesign; % Create design variable.<\/span>\r\n\r\nif<\/span> ~isstruct(design) || ~all(isfield(design,{'c'<\/span>,'k'<\/span>}))\r\n    error('simulateSystem:InvalidDesign:ShouldBeStruct'<\/span>, ...<\/span>\r\n        'The design should be a structure with fields \"c\" and \"k\"'<\/span>);\r\nend<\/span>\r\n\r\n% Design variables<\/span>\r\nc = design.c;\r\nk = design.k;\r\n\r\n% Constant variables<\/span>\r\nz0 = [-0.1; 0];  % Initial Position and Velocity<\/span>\r\nm = 1500;        % Mass<\/span>\r\n\r\nodefun = @(t,z) [0 1; -k\/m -c\/m]*z;\r\n[t, z] = ode45(odefun, [0, 3], z0);\r\n\r\n% The first column is the position (displacement from equilibrium)<\/span>\r\nx = z(:, 1);\r\n\r\n<\/pre>
...as well as a corresponding script which defines the design of the system in terms of the spring stiffness and damping:<\/p>
\r\nm = 1500; % Need to know the mass to determine critical damping<\/span>\r\n\r\ndesign.k = 5e6;                   % Spring Constant<\/span>\r\ndesign.c = 2*m*sqrt(design.k\/m); % Damping Coefficient to be critically damped<\/span>\r\n\r\nclear m<\/span>;\r\n\r\n<\/pre>
Along with this source we also have a file that defines a couple tests for this design to ensure it achieves the right characteristics in terms of acceptable overshoot and settling time of a step response:<\/p>
\r\nfunction<\/span> tests = designTest\r\ntests = functiontests(localfunctions); \r\nend<\/span>\r\n\r\nfunction<\/span> testSettlingTime(testCase) \r\n%%Test that the system settles to within 0.001 of zero under 2 seconds.<\/span>\r\n\r\n[position, time] = simulateSystem; \r\n\r\npositionAfterSettling = position(time > .002);\r\n\r\n%For this example, verify the first value after the settling time.<\/span>\r\nverifyLessThan(testCase, abs(positionAfterSettling), 2);\r\nend<\/span>\r\n\r\nfunction<\/span> testOvershoot(testCase)\r\n %Test to ensure that overshoot is less than 0.01<\/span>\r\n\r\n[position, time] = simulateSystem;\r\novershoot = max(position);\r\n\r\nverifyLessThan(testCase, overshoot, 0.01);\r\nend<\/span>\r\n\r\n<\/pre>
Finally, here is our test running script that will kick off the testing:<\/p>
\r\ntry<\/span>\r\n    import('matlab.unittest.TestRunner'<\/span>);\r\n    import('matlab.unittest.plugins.XMLPlugin'<\/span>);\r\n    import('matlab.unittest.plugins.ToFile'<\/span>);\r\n\r\n    \r\n    ws = getenv('WORKSPACE'<\/span>);\r\n    \r\n    src = fullfile(ws, 'source'<\/span>);\r\n    addpath(src);\r\n    \r\n    tests = fullfile(ws, 'tests'<\/span>);\r\n    suite = testsuite(tests);\r\n\r\n    % Create and configure the runner<\/span>\r\n    runner = TestRunner.withTextOutput('Verbosity'<\/span>,3);\r\n\r\n    % Add the plugin for test results<\/span>\r\n    resultsDir = fullfile(ws, 'testresults'<\/span>);\r\n    mkdir(resultsDir);\r\n    resultsFile = fullfile(resultsDir, 'testResults.xml'<\/span>);\r\n    runner.addPlugin(XMLPlugin.producingJUnitFormat(resultsFile));\r\n     \r\n    results = runner.run(suite)\r\ncatch<\/span> e\r\n    disp(getReport(e,'extended'<\/span>));\r\n    exit(1);\r\nend<\/span>\r\nquit('force'<\/span>);\r\n\r\n<\/pre>
With this set up you can see that each build actually gives us four different configurations so we test across all releases.<\/p>
\"\" <\/p>
\"\" <\/p>
Here we see we are just fine to upgrade to R2017b. How's that for some peace of mind? Trusting your tests gives you the confidence needed to upgrade without worry and\/or to be notified quickly when adjustments need to be made.<\/p>
Now let's evolve the code. I am not the biggest fan of the design script because it offends my sensibilities to have the clear m<\/tt> call in there. I'd like to change this implementation:<\/p>
\r\nm = 1500; % Need to know the mass to determine critical damping<\/span>\r\n\r\ndesign.k = 5e6;                   % Spring Constant<\/span>\r\ndesign.c = 2*m*sqrt(design.k\/m); % Damping Coefficient to be critically damped<\/span>\r\n\r\nclear m<\/span>;\r\n\r\n<\/pre>
...to this:<\/p>
\r\ndesign.k = 5e6;                   % Spring Constant<\/span>\r\ndesign.c = 2*getMass*sqrt(design.k\/getMass); % Damping Coefficient to be critically damped<\/span>\r\n\r\nfunction<\/span> m = getMass\r\nm = 1500; % Need to know the mass to determine critical damping<\/span>\r\nend<\/span>\r\n\r\n<\/pre>
This seems cleaner to me. I'd rather leverage a local function in the script so that the variable we'd like to clear simply never is created in the workspace.<\/p>
However, checking this change in produces the following:<\/p>
\"\" <\/p>
\"\" <\/p>
It looks like local functions in scripts weren't around in R2016a, so I'll have to wait on that change until I no longer need to support my code in that release. Thanks, build matrix!<\/p>