Merge pull request #176 from mathworks/3.0.0-Qualification

3.0.0 qualification -> 2.4.0 Release

Author: abhargav-mw

CONFIGDOC.md

@@ -4,9 +4,9 @@ This example shows how to run a suite of MATLAB® unit tests with Jenkins&tra
 
 * Configure Jenkins to run a freestyle project including MATLAB tests.
 * Interface Jenkins with a remote repository that contains the tests.
-* Build the freestyle project and examine the generated test artifacts.
+* Build the freestyle project and examine the generated artifacts.
 
-The freestyle project runs the tests in the Times Table App MATLAB project (which requires R2019a or later). You can create a working copy of the project files and open the project in MATLAB by running this statement in the Command Window: 
+The freestyle project runs the tests in the Times Table App MATLAB project (which requires R2019a or later). You can create a working copy of the project files and open the project in MATLAB by running this statement in the Command Window.
 
 ```
 matlab.project.example.timesTable
@@ -17,62 +17,58 @@ For more information about the Times Table App example project, see [Explore an
 ## Prerequisites
 Running the tests in this example requires you to interface Jenkins with MATLAB as well as a remote repository.
 
-* To run MATLAB tests and generate test artifacts, you must install the MATLAB plugin. For information on how to install a plugin in Jenkins, see [Managing Plugins](https://jenkins.io/doc/book/managing/plugins/).
+* To run MATLAB tests and generate artifacts, you must install the plugin for MATLAB. For information on how to install a plugin in Jenkins, see [Managing Plugins](https://jenkins.io/doc/book/managing/plugins/).
 * Jenkins runs the tests in a branch of the remote repository that is specified by a URL. To follow the build steps in this example, the Times Table App project must be under Git™ source control. For example, you can create a new repository for the project using your GitHub® account. For more information, see [Use Source Control with Projects](https://www.mathworks.com/help/matlab/matlab_prog/use-source-control-with-projects.html).
-* To publish the test artifacts using post-build actions, relevant plugins must be installed on Jenkins. For example, the [Cobertura plugin](https://plugins.jenkins.io/cobertura) integrates Cobertura coverage reports to Jenkins, and [JUnit plugin](https://plugins.jenkins.io/junit) publishes JUnit-format test results. 
+* To publish the artifacts using post-build actions, relevant plugins must be installed on Jenkins. For example, the [Cobertura plugin](https://plugins.jenkins.io/cobertura) integrates Cobertura coverage reports to Jenkins, and [JUnit plugin](https://plugins.jenkins.io/junit) publishes JUnit-format test results. 
 
 ## Configure Jenkins Project to Run MATLAB Tests
 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, then click **Freestyle project**. To confirm your choices, click **OK**.
 
-![create_project](https://user-images.githubusercontent.com/48831250/94477040-50aee880-019f-11eb-9484-1d4ecf60ed92.png)
+![create_project](https://user-images.githubusercontent.com/48831250/105080784-520e6480-5a5f-11eb-9218-4d43013e2850.png)
 
 2. In the configuration window of your Jenkins project, navigate to the **Source Code Management** section and click **Git**. This option enables Jenkins to interface with a remote repository.
 
-![git](https://user-images.githubusercontent.com/48831250/94477376-cb780380-019f-11eb-8297-1c3a4874fe0e.png)
-
-
 3. Navigate to the main page of the GitHub repository that hosts your tests. Click **Code** and copy the web URL to your clipboard.
 
 ![clipboard](https://user-images.githubusercontent.com/48831250/94478137-dd0ddb00-01a0-11eb-9e55-d8004863c5e7.png)
 
 
-4. In the Jenkins interface, paste the URL into the **Repository URL** box of the **Source Code Management** section. You also can specify the branch to build in the **Branch Specifier** box.
+4. In the project configuration window, paste the URL into the **Repository URL** box of the **Source Code Management** section. You also can specify the branch to build in the **Branch Specifier** box.
 
 ![source_control](https://user-images.githubusercontent.com/48831250/94478391-37a73700-01a1-11eb-9f89-a5a71413baf0.png)
 
 
-5. In the **Build Environment** section of Jenkins, select **Use MATLAB Version**. Then, enter the full path to the MATLAB root folder in the **MATLAB root** box. Jenkins uses MATLAB at the specified location to run the tests. 
-
-![build_environment](https://user-images.githubusercontent.com/48831250/94478737-ad130780-01a1-11eb-89d8-1ef43c34fab0.png)
+5. 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. 
 
-6. In the **Build** section of Jenkins, select **Add build step > Run MATLAB Tests**. Then, select your desired test artifacts to be generated in the project workspace. The plugin in this example is configured to generate Cobertura code coverage and JUnit test result reports. Furthermore, the coverage report is generated only for the code in the `source` folder located in the root of your repository. For more information on how to configure the plugin, see [Plugin Configuration Guide](../CONFIGDOC.md).
+![build_environment](https://user-images.githubusercontent.com/48831250/105091260-943ea280-5a6d-11eb-8d11-48747df7ec32.png)
 
-![run_matlab_tests](https://user-images.githubusercontent.com/48831250/94479048-2f9bc700-01a2-11eb-9ff6-4ab1df99d1b9.png)
+6. In the **Build** section, select **Add build step > Run MATLAB Tests**. Then, select your desired artifacts to be generated in the project workspace. The plugin in this example is configured to generate Cobertura code coverage and JUnit test result reports. Furthermore, the coverage report is generated only for the code in the `source` folder located in the root of your repository. For more information on how to configure the plugin, see [Plugin Configuration Guide](../CONFIGDOC.md).
 
-7. In the **Post-build Actions** section of Jenkins, add two post-build actions to publish the Cobertura code coverage and JUnit test result reports. For each report, provide the path to the report file.
+![run_matlab_tests](https://user-images.githubusercontent.com/48831250/105909903-2149a480-5ff6-11eb-81f1-c3b44e9b17d1.png)
 
-![post_build](https://user-images.githubusercontent.com/48831250/94479293-96b97b80-01a2-11eb-97ff-44a321bce0e9.png)
+7. In the **Post-build Actions** section, add two post-build actions to publish the Cobertura code coverage and JUnit test result reports. For each report, provide the path to the report file.
 
+![post_build](https://user-images.githubusercontent.com/48831250/105082096-14aad680-5a61-11eb-9868-68d018199f9d.png)
 
 8. 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.
 
-## Run Tests and Inspect Test Artifacts
-To build your Jenkins project and run the tests specified in the repository, click **Build Now** in the project interface, which displays the project name at the top-left of the page. 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 passes because all of the tests specified in the Times Table App project pass.
+## Run Tests and Inspect Artifacts
+To build your freestyle project, click **Build Now** in the project interface, which displays the project name at the top-left of the page. 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 passes because all of the tests in the Times Table App project pass.
 
-![build_1](https://user-images.githubusercontent.com/48831250/94481160-4db6f680-01a5-11eb-83eb-75027a009321.png)
+![build_1](https://user-images.githubusercontent.com/48831250/105084788-dca59280-5a64-11eb-858d-664a5727a947.png)
 
-Navigate to the project workspace by clicking the **Workspace** icon in the project interface. In this example, the generated test artifacts are in the `matlabTestArtifacts` folder of the workspace.
+Navigate to the project workspace by clicking the **Workspace** icon in the project interface. In this example, the generated artifacts are in the `matlabTestArtifacts` folder of the workspace.
 
-![workspace](https://user-images.githubusercontent.com/48831250/94481319-88209380-01a5-11eb-8681-440ea84b59d9.png)
+![workspace](https://user-images.githubusercontent.com/48831250/105085419-b46a6380-5a65-11eb-8d46-747dd23291bf.png)
 
 Access the published Cobertura code coverage report by opening the **Coverage Report** link in the project interface.
 
-![cobertura_report](https://user-images.githubusercontent.com/48831250/94481556-e2b9ef80-01a5-11eb-86f2-1679ae63f407.png)
+![cobertura_report](https://user-images.githubusercontent.com/48831250/105085331-9ac91c00-5a65-11eb-9628-efbf70520489.png)
 
 To view the published JUnit test results, open the **Latest Test Result** link in the project interface. 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.  
 
-![junit_report](https://user-images.githubusercontent.com/48831250/94481735-33c9e380-01a6-11eb-9106-d96cfd7676ae.png)
+![junit_report](https://user-images.githubusercontent.com/48831250/105088211-956dd080-5a69-11eb-931c-aef201eb9dbe.png)
 
 ## See Also
 [MathWorks Blogs: Developer Zone – Continuous Integration](https://blogs.mathworks.com/developer/category/continuous-integration/)<br/>

examples/Run-MATLAB-Tests.md

@@ -0,0 +1,30 @@
+package com.mathworks.ci;
+
+/**
+ * Copyright 2020 The MathWorks, Inc.
+ *
+ * Class to parse Stapler request for Use MATLAB Version build wrapper.
+ *
+ */
+
+import org.kohsuke.stapler.DataBoundConstructor;
+
+public class MatlabBuildWrapperContent {
+
+    private final String matlabInstallationName;
+    private final String matlabRootFolder;
+
+    @DataBoundConstructor
+    public MatlabBuildWrapperContent(String matlabInstallationName, String matlabRootFolder){
+        this.matlabInstallationName = matlabInstallationName;
+        this.matlabRootFolder = matlabRootFolder;
+    }
+
+    public String getMatlabInstallationName() {
+        return matlabInstallationName;
+    }
+
+    public String getMatlabRootFolder() {
+        return matlabRootFolder;
+    }
+}

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

@@ -1,5 +1,12 @@
 package com.mathworks.ci;
 
+/**
+ * Copyright 2020 The MathWorks, Inc.
+ *
+ * Describable class for adding MATLAB installations in Jenkins Global Tool configuration.
+ *
+ */
+
 import hudson.CopyOnWrite;
 import hudson.EnvVars;
 import hudson.Extension;
@@ -15,6 +22,9 @@
 import java.util.Arrays;
 import java.util.List;
 import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
+
+import jenkins.model.Jenkins;
 import net.sf.json.JSONObject;
 import org.jenkinsci.Symbol;
 import org.kohsuke.stapler.DataBoundConstructor;
@@ -28,12 +38,20 @@ public MatlabInstallation(String name, @CheckForNull String home, List<? extends
         super(Util.fixEmptyAndTrim(name), Util.fixEmptyAndTrim(home), properties);
     }
 
+    /*
+    * Constructor for Custom object
+    * */
+
+    public MatlabInstallation(String name){
+        super(name, null, null);
+    }
+
     @Override public MatlabInstallation forEnvironment(EnvVars envVars) {
         return new MatlabInstallation(getName(), envVars.expand(getHome()), getProperties().toList());
     }
 
     @Override
-    public MatlabInstallation forNode(Node node, TaskListener log) throws IOException, InterruptedException {
+    public MatlabInstallation forNode(@Nonnull Node node, TaskListener log) throws IOException, InterruptedException {
         return new MatlabInstallation(getName(), translateFor(node, log), getProperties().toList());
     }
 
@@ -43,6 +61,23 @@ public void buildEnvVars(EnvVars env) {
         env.put("PATH+matlabroot", pathToExecutable);
     }
 
+    public static MatlabInstallation[] getAll () {
+        return Jenkins.get().getDescriptorByType(DescriptorImpl.class).getInstallations();
+    }
+
+    public static boolean isEmpty() {
+        return getAll().length == 0;
+    }
+
+    public static MatlabInstallation getInstallation(String name) {
+        for (MatlabInstallation inst : getAll()) {
+            if (name.equals(inst.getName())) {
+                return inst;
+            }
+        }
+        return null;
+    }
+
     @Extension @Symbol("matlab")
     public static class DescriptorImpl extends ToolDescriptor<MatlabInstallation> {
         @CopyOnWrite
@@ -71,7 +106,5 @@ public void setInstallations(MatlabInstallation... matlabInstallations) {
             this.installations = matlabInstallations;
             save();
         }
-
     }
-
 }

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

@@ -0,0 +1,69 @@
+package com.mathworks.ci;
+
+/**
+ * Copyright 2020 The MathWorks, Inc.
+ *
+ * Describable class for MATLAB Axis that provides a list of configured MATLAB installation for
+ * generating matrix configurations.
+ *
+ */
+
+import hudson.Extension;
+import hudson.matrix.Axis;
+import hudson.matrix.AxisDescriptor;
+import hudson.matrix.MatrixProject;
+import org.kohsuke.stapler.DataBoundConstructor;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+public class MatlabInstallationAxis extends Axis {
+
+    @DataBoundConstructor
+    public MatlabInstallationAxis(List<String> values) {
+        super(Message.getValue("Axis.matlab.key"), evaluateValues(values));
+    }
+
+    static private List<String> evaluateValues(List<String> values) {
+        // Add default configuration is values are null or not selected.
+        if (values == null || values.isEmpty()) {
+            values = new ArrayList<>(Arrays.asList("default"));
+        }
+        return values;
+    }
+
+    @Extension
+    public static class DescriptorImpl extends AxisDescriptor{
+
+        @Override
+        public String getDisplayName() {
+            return Message.getValue("Axis.matlab.key");
+        }
+
+        @Override
+        public boolean isInstantiable() {
+            return !isMatlabInstallationEmpty();
+        }
+
+        public boolean checkUseMatlabVersion(Object it) {
+            return MatlabItemListener.getMatlabBuildWrapperCheckForPrj(((MatrixProject) it).getFullName()) && !isMatlabInstallationEmpty();
+        }
+
+        public MatlabInstallation[] getInstallations () {
+            return MatlabInstallation.getAll();
+        }
+
+        public String getUseMatlabWarning() {
+            return Message.getValue("Axis.use.matlab.warning");
+        }
+
+        public boolean isMatlabInstallationEmpty() {
+            return MatlabInstallation.isEmpty();
+        }
+
+        public String getNoInstallationError() {
+            return Message.getValue("Axis.no.installed.matlab.error");
+        }
+    }
+}

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

@@ -0,0 +1,91 @@
+package com.mathworks.ci;
+
+/**
+ * Copyright 2020 The MathWorks, Inc.
+ *
+ * Item listener class to provide functionality to check UI element states for a
+ * Multi-configuration project.
+ *
+ */
+
+import hudson.Extension;
+import hudson.matrix.MatrixConfiguration;
+import hudson.matrix.MatrixProject;
+import hudson.model.Item;
+import hudson.model.TopLevelItem;
+import hudson.model.listeners.ItemListener;
+import jenkins.model.Jenkins;
+
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+@Extension
+public final class MatlabItemListener extends ItemListener {
+    private static final Map<String, Boolean> prjCheckMatlabAxis = new HashMap<>();
+    private static final Map<String, Boolean> prjCheckMatlabBuildWrapper = new HashMap<>();
+
+    @Override
+    public void onLoaded(){
+        checkItems(Jenkins.get().getItems());
+    }
+
+    @Override
+    public void onUpdated(Item item) {
+        if(!(item instanceof MatrixProject)){
+            return;
+        }
+        checkSingleItem(item);
+    }
+
+
+    private void checkItems(List<TopLevelItem> items) {
+        for(TopLevelItem item : items){
+            if(item instanceof MatrixProject){
+                check((MatrixProject) item);
+            }
+        }
+    }
+
+    private void checkSingleItem(Item item){
+        check((MatrixProject) item);
+    }
+
+    private void check(MatrixProject prj) {
+        checkForAxis(prj);
+        checkForBuildWrapper(prj);
+    }
+
+    private void checkForAxis(MatrixProject prj) {
+        boolean checkForAxis = false;
+        Collection<MatrixConfiguration> configurations = prj.getActiveConfigurations();
+        for(MatrixConfiguration conf : configurations){
+            String matlabAxisValue = conf.getCombination().get(Message.getValue("Axis.matlab.key"));
+            if (matlabAxisValue != null) {
+                checkForAxis = true;
+                break;
+            }
+        }
+        prjCheckMatlabAxis.put(prj.getFullName(), checkForAxis);
+    }
+
+    private void checkForBuildWrapper(MatrixProject prj) {
+        boolean checkForBuildWrapper = false;
+        for(Object bWrapper : prj.getBuildWrappersList().toArray()) {
+            if(bWrapper instanceof UseMatlabVersionBuildWrapper){
+                checkForBuildWrapper = ((UseMatlabVersionBuildWrapper) bWrapper).getMatlabInstallationName() != null;
+                break;
+            }
+        }
+        prjCheckMatlabBuildWrapper.put(prj.getFullName(), checkForBuildWrapper);
+    }
+
+    public static boolean getMatlabAxisCheckForPrj(String prjName) {
+        return prjCheckMatlabAxis.get(prjName) != null && prjCheckMatlabAxis.get(prjName);
+    }
+
+    public static boolean getMatlabBuildWrapperCheckForPrj(String prjName) {
+        return prjCheckMatlabBuildWrapper.get(prjName) != null && prjCheckMatlabBuildWrapper.get(prjName);
+    }
+}