Merge pull request #238 from mathworks/2.9.1-SNAPSHOT-Qualification

2.9.1 snapshot qualification (2.10.0)

Author: nbhoski

.gitignore

@@ -0,0 +1,10 @@
+# Jenkins development server folders
+target
+work
+
+# Binaries and downloaded resources
+src/main/resources/matlab-script-generator.zip
+src/main/resources/run_matlab_command.*
+src/main/resources/license.txt
+
+**/.DS_Store

CONFIGDOC.md

@@ -1,5 +1,5 @@
 # Continuous Integration with MATLAB on Jenkins
-This plugin enables you to run MATLAB® scripts, functions, and statements as part of your build. You also can run MATLAB and Simulink® tests, and generate test and coverage artifacts such as JUnit-style test results and Cobertura code and model coverage reports.
+This plugin enables you to build and test your MATLAB® project as part of your Jenkins™ build. For example, you can automatically identify any code issues in your project, run tests and generate test and coverage artifacts, and package your files into a toolbox.
 
 ## Releases
 For a detailed list of releases, see [Change Logs](/CHANGELOG.md). 

README.md

@@ -6,7 +6,7 @@
 strategy:
   matrix:
     linux:
-      imageName: 'ubuntu-18.04'
+      imageName: 'ubuntu-latest'
     mac:
       imageName: 'macOS-10.15'
     windows:

azure-pipelines.yml

@@ -24,37 +24,37 @@ To follow the steps in this example:
 Create a new project and configure it by following these steps:
 1. In your Jenkins interface, select **New Item** on the left. A new page opens where you can choose the type of your project. Enter a project name, and then click **Freestyle project**. To confirm your choices, click **OK**.
 
-![create_project](https://user-images.githubusercontent.com/48831250/193948023-65f038c2-a81e-416b-8dea-0cf91ae5f105.png)
+![create_project](https://user-images.githubusercontent.com/48831250/217659170-43474c58-d6a1-44fa-bf72-eafe2aca49bb.png)
 
 2. On the project configuration page, in the **Source Code Management** section, specify the repository that hosts your tests.
 
-![source_control](https://user-images.githubusercontent.com/48831250/94478391-37a73700-01a1-11eb-9f89-a5a71413baf0.png)
+![source_control](https://user-images.githubusercontent.com/48831250/217660122-eddabcd5-cab1-4c41-a175-3641457b6d2c.png)
 
-3. In the **Build Environment** section, select **Use MATLAB version** and specify the MATLAB version you want to use in the build. If your desired MATLAB version is not listed under **Use MATLAB version**, enter the full path to its root folder in the **MATLAB root** box. 
+3. In the **Build Environment** section, select **Use MATLAB version** and specify the MATLAB version you want to use in the build. If your preferred MATLAB version is not listed under **Use MATLAB version**, enter the full path to its root folder in the **MATLAB root** box. 
 
-![build_environment](https://user-images.githubusercontent.com/48831250/193948480-564ac249-0ef2-407b-b18c-ee52b5129ac0.png)
+![build_environment](https://user-images.githubusercontent.com/48831250/217660546-65dc1045-2e4b-4e4b-a1cb-c4b0fedbdbc3.png)
 
-4. In the **Build** section, select **Add build step > Run MATLAB Tests**. Then, specify the artifacts to be generated in the project workspace. In this example, the plugin generates Cobertura code coverage and JUnit-style test results reports. Furthermore, to generate the coverage report, the plugin uses only the code in the `source` folder located in the root of the repository. For more information about the build steps provided by the plugin, see [Plugin Configuration Guide](../CONFIGDOC.md).
+4. In the **Build Steps** section, select **Add build step > Run MATLAB Tests**. Then, specify the artifacts to be generated in the project workspace. In this example, the plugin generates test results in JUnit XML format and code coverage results in Cobertura XML format. Furthermore, to generate the coverage results, the plugin uses only the code in the `source` folder located in the root of the repository. For more information about the build steps provided by the plugin, see [Plugin Configuration Guide](../CONFIGDOC.md).
 
-![run_,matlab_tests](https://user-images.githubusercontent.com/48831250/193948891-aa09960a-04ba-4a13-9eea-e4bebab9371d.png)
+![run_matlab_tests](https://user-images.githubusercontent.com/48831250/217660935-7b6fbcda-5149-4863-983c-64360b8edd07.png)
 
-5. In the **Post-build Actions** section, add two post-build actions to publish the Cobertura code coverage and JUnit-style test results reports. For each artifact, provide the path to the report.
+5. In the **Post-build Actions** section, add two post-build actions to publish the JUnit-style test results and the Cobertura code coverage results. For each artifact, provide the path to the report.
 
-![post_build](https://user-images.githubusercontent.com/48831250/193949176-aced5dfb-f7b9-4978-8726-7d01bae4bc97.png)
+![post_build](https://user-images.githubusercontent.com/48831250/217661749-c0ed8340-9fe8-4f88-82f9-f91c2737259d.png)
 
-6. Click **Save** to save the project configuration settings. You can access and modify your settings at a later stage by selecting **Configure** in the project interface, which displays the project name at the top-left of the page.
+6. Click **Save** to save the project configuration settings. You can access and modify your settings at a later stage by selecting **Configure** in the project interface, which displays the project name at the upper-left corner of the page.
 
 ## Run Tests and Inspect Artifacts
-To build your freestyle project, click **Build Now** in the project interface. Jenkins triggers a build, assigns it a number under **Build History**, and runs the build. If the build is successful, a blue circle icon appears next to the build number. If the build fails, Jenkins adds a red circle icon. In this example, the build succeeds because all the tests in the Times Table App project pass.
+To build your freestyle project, click **Build Now** in the project interface. Jenkins triggers a build, assigns it a number under **Build History**, and runs the build. If the build succeeds, a green icon appears next to the build number. If the build fails, Jenkins adds a red icon. In this example, the build succeeds because all the tests in the Times Table App project pass.
 
 Navigate to the project workspace by clicking the **Workspace** icon in the project interface. The generated artifacts are in the `matlabTestArtifacts` folder of the workspace.
 
-![workspace](https://user-images.githubusercontent.com/48831250/193951807-a09ef1f8-cf7e-49c8-8615-af5fbd97acd0.png)
+![workspace](https://user-images.githubusercontent.com/48831250/217663519-d5a4c5bb-43e5-4ff4-ae32-c4b5e1181da7.png)
 
-Click the **Status** icon in the project interface. You can access the published artifacts by opening the **Latest Test Result** and **Coverage Report** links. For example, open the **Latest Test Result** link to view the published JUnit-style test results. In the new page, open the link in the **All Tests** table. The table expands and lists information for each of the test classes within the Times Table App project.  
+Click the **Status** icon in the project interface. You can access the published artifacts by clicking the **Latest Test Result** and **Coverage Report** links. For example, click the **Latest Test Result** link to view the published JUnit-style test results. On the test results page, click the **(root)** link in the **All Tests** table. The table expands and lists information for each of the test classes within the Times Table App project.  
 
-![test_results](https://user-images.githubusercontent.com/48831250/194086287-35f7c677-4c18-4316-b676-f2491ffa20a7.png)
+![test_results](https://user-images.githubusercontent.com/48831250/217663985-14b433e2-7546-40b1-a2e3-34d56f1f11ff.png)
 
 ## See Also
 * [Plugin Configuration Guide](../CONFIGDOC.md)<br/>
-* [Explore an Example Project (MATLAB)](https://www.mathworks.com/help/matlab/matlab_prog/explore-an-example-project.html)
+* [Explore an Example Project (MATLAB)](https://www.mathworks.com/help/matlab/matlab_prog/explore-an-example-project.html)

examples/Run-MATLAB-Tests.md

@@ -0,0 +1,107 @@
+package com.mathworks.ci;
+
+/**
+ * Copyright 2022 The MathWorks, Inc.
+ *  
+ */
+
+import java.io.IOException;
+import org.jenkinsci.plugins.workflow.steps.StepContext;
+import org.jenkinsci.plugins.workflow.steps.SynchronousNonBlockingStepExecution;
+import hudson.EnvVars;
+import hudson.FilePath;
+import hudson.Launcher;
+import hudson.Launcher.ProcStarter;
+import hudson.model.Result;
+import hudson.model.TaskListener;
+
+public class MatlabBuildStepExecution extends SynchronousNonBlockingStepExecution<Void> implements MatlabBuild {
+    
+    private static final long serialVersionUID = 4771831219402275744L;
+    
+    private String tasks;
+
+    public MatlabBuildStepExecution(StepContext context, String tasks) {
+        super(context);
+        this.tasks = tasks;
+    }
+
+    private String getTasks() {
+        return this.tasks;
+    }
+
+    @Override
+    public Void run() throws Exception {
+        final Launcher launcher = getContext().get(Launcher.class);
+        final FilePath workspace = getContext().get(FilePath.class);
+        final TaskListener listener = getContext().get(TaskListener.class);
+        final EnvVars env = getContext().get(EnvVars.class);
+        
+        //Make sure the Workspace exists before run
+        
+        workspace.mkdirs();
+        
+        int exitCode = execMatlabCommand(workspace, launcher, listener, env);
+
+        if(exitCode != 0){
+            // throw an exception if return code is non-zero
+            stop(new MatlabExecutionException(exitCode));
+        }
+
+        getContext().setResult(Result.SUCCESS);
+        return null;
+    }
+
+    @Override
+    public void stop(Throwable cause) throws Exception {
+        getContext().onFailure(cause);
+    }
+    
+    private int execMatlabCommand(FilePath workspace, Launcher launcher,
+            TaskListener listener, EnvVars envVars) throws IOException, InterruptedException {
+        final String uniqueTmpFldrName = getUniqueNameForRunnerFile();  
+        final String uniqueBuildFile =
+                "build_" + getUniqueNameForRunnerFile().replaceAll("-", "_");
+        final FilePath uniqueTmpFolderPath =
+                getFilePathForUniqueFolder(launcher, uniqueTmpFldrName, workspace);
+
+        // Create MATLAB script
+        createMatlabScriptByName(uniqueTmpFolderPath, uniqueBuildFile, workspace, listener);
+        ProcStarter matlabLauncher;
+
+        try {
+            matlabLauncher = getProcessToRunMatlabCommand(workspace, launcher, listener, envVars,
+                    "cd('"+ uniqueTmpFolderPath.getRemote().replaceAll("'", "''") +"'); "+ uniqueBuildFile, uniqueTmpFldrName);
+            listener.getLogger()
+                    .println("#################### Starting command output ####################");
+            return matlabLauncher.pwd(workspace).join();
+
+        } finally {
+            // Cleanup the tmp directory
+            if (uniqueTmpFolderPath.exists()) {
+                uniqueTmpFolderPath.deleteRecursive();
+            }
+        }
+    }
+    
+    private void createMatlabScriptByName(FilePath uniqeTmpFolderPath, String uniqueScriptName, FilePath workspace, TaskListener listener) throws IOException, InterruptedException {
+
+        // Create a new command runner script in the temp folder.
+        final FilePath matlabBuildFile =
+                new FilePath(uniqeTmpFolderPath, uniqueScriptName + ".m");
+        final String tasks = getContext().get(EnvVars.class).expand(getTasks());
+        String cmd = "buildtool";
+
+        if (!tasks.trim().isEmpty()) {
+            cmd += " " + tasks;
+        }
+        final String matlabBuildFileContent =
+                "cd '" + workspace.getRemote().replaceAll("'", "''") + "';\n" + cmd;
+
+        // Display the commands on console output for users reference
+        listener.getLogger()
+                .println("Generating MATLAB script with content:\n" + cmd + "\n");
+
+        matlabBuildFile.write(matlabBuildFileContent, "UTF-8");
+    }
+}

src/main/java/com/mathworks/ci/MatlabBuildStepExecution.java

@@ -0,0 +1,152 @@
+package com.mathworks.ci;
+
+/**
+ * Copyright 2022 The MathWorks, Inc.
+ *  
+ */
+
+import java.io.IOException;
+import javax.annotation.Nonnull;
+import org.kohsuke.stapler.DataBoundConstructor;
+import org.kohsuke.stapler.DataBoundSetter;
+import org.kohsuke.stapler.StaplerRequest;
+import hudson.EnvVars;
+import hudson.Extension;
+import hudson.FilePath;
+import hudson.Launcher;
+import hudson.Launcher.ProcStarter;
+import hudson.model.AbstractProject;
+import hudson.model.Result;
+import hudson.model.Run;
+import hudson.model.TaskListener;
+import hudson.model.Computer;
+import hudson.tasks.BuildStepDescriptor;
+import hudson.tasks.Builder;
+import jenkins.tasks.SimpleBuildStep;
+import net.sf.json.JSONObject;
+
+public class RunMatlabBuildBuilder extends Builder implements SimpleBuildStep, MatlabBuild {
+    private int buildResult;
+    private String tasks;
+
+    @DataBoundConstructor
+    public RunMatlabBuildBuilder() {}
+
+    // Getter and Setters to access local members
+    @DataBoundSetter
+    public void setTasks(String tasks) {
+        this.tasks = tasks;
+    }
+
+    public String getTasks() {
+        return this.tasks;
+    }
+    
+    @Extension
+    public static class RunMatlabBuildDescriptor extends BuildStepDescriptor<Builder> {
+
+        // Overridden Method used to show the text under build dropdown
+        @Override
+        public String getDisplayName() {
+            return Message.getValue("Builder.build.builder.display.name");
+        }
+
+        @Override
+        public boolean configure(StaplerRequest req, JSONObject formData) throws FormException {
+            save();
+            return super.configure(req, formData);
+        }
+
+        /*
+         * This is to identify which project type in jenkins this should be applicable.(non-Javadoc)
+         * 
+         * @see hudson.tasks.BuildStepDescriptor#isApplicable(java.lang.Class)
+         * 
+         * if it returns true then this build step will be applicable for all project type.
+         */
+        @Override
+        public boolean isApplicable(
+                @SuppressWarnings("rawtypes") Class<? extends AbstractProject> jobtype) {
+            return true;
+        }
+    }
+
+    @Override
+    public void perform(@Nonnull Run<?, ?> build, @Nonnull FilePath workspace,
+            @Nonnull Launcher launcher, @Nonnull TaskListener listener)
+            throws InterruptedException, IOException {
+
+        // Get the environment variable specific to the this build
+        final EnvVars env = build.getEnvironment(listener);
+
+        // Invoke MATLAB build and transfer output to standard
+        // Output Console
+
+
+        buildResult = execMatlabCommand(workspace, launcher, listener, env);
+
+        if (buildResult != 0) {
+            build.setResult(Result.FAILURE);
+        }
+    }
+
+    private int execMatlabCommand(FilePath workspace, Launcher launcher,
+            TaskListener listener, EnvVars envVars) throws IOException, InterruptedException {
+
+        /*
+         * Handle the case for using MATLAB Axis for multi conf projects by adding appropriate
+         * matlabroot to env PATH
+         * */
+        Utilities.addMatlabToEnvPathFrmAxis(Computer.currentComputer(), listener, envVars);
+
+        final String uniqueTmpFldrName = getUniqueNameForRunnerFile();
+        final String uniqueBuildFile =
+                "build_" + getUniqueNameForRunnerFile().replaceAll("-", "_");
+        final FilePath uniqeTmpFolderPath =
+                getFilePathForUniqueFolder(launcher, uniqueTmpFldrName, workspace);
+
+        // Create MATLAB script
+        createMatlabScriptByName(uniqeTmpFolderPath, uniqueBuildFile, workspace, listener, envVars);
+        ProcStarter matlabLauncher;
+
+        try {
+            matlabLauncher = getProcessToRunMatlabCommand(workspace, launcher, listener, envVars,
+                    "cd('"+ uniqeTmpFolderPath.getRemote().replaceAll("'", "''") +"');"+ uniqueBuildFile, uniqueTmpFldrName);
+            
+            listener.getLogger()
+                    .println("#################### Starting command output ####################");
+            return matlabLauncher.pwd(workspace).join();
+
+        } catch (Exception e) {
+            listener.getLogger().println(e.getMessage());
+            return 1;
+        } finally {
+            // Cleanup the tmp directory
+            if (uniqeTmpFolderPath.exists()) {
+                uniqeTmpFolderPath.deleteRecursive();
+            }
+        }
+    }
+    
+    private void createMatlabScriptByName(FilePath uniqeTmpFolderPath, String uniqueScriptName, FilePath workspace, TaskListener listener, EnvVars envVars) throws IOException, InterruptedException {
+
+        // Create a new command runner script in the temp folder.
+        final FilePath matlabCommandFile =
+                new FilePath(uniqeTmpFolderPath, uniqueScriptName + ".m");
+        final String tasks = envVars.expand(getTasks());
+        String cmd = "buildtool";
+
+        if (!tasks.trim().isEmpty()) {
+            cmd += " " + tasks;
+        }
+
+        final String matlabCommandFileContent =
+                "cd '" + workspace.getRemote().replaceAll("'", "''") + "';\n" + cmd;
+
+        // Display the commands on console output for users reference
+        listener.getLogger()
+                .println("Generating MATLAB script with content:\n" + cmd + "\n");
+
+        matlabCommandFile.write(matlabCommandFileContent, "UTF-8");
+    }
+}