Merge pull request #165 from mathworks/tool_config_doc

Document the support for global tool configuration

Author: abhargav-mw

CONFIGDOC.md

@@ -13,6 +13,8 @@ When you define an automated pipeline of tasks in Jenkins™, whether in the
    -  [Use the runMATLABCommand Step](#use-the-runmatlabcommand-step)
    -  [Use the runMATLABTests Step](#use-the-runmatlabtests-step) 
    -  [Use MATLAB in Matrix Build](#use-matlab-in-matrix-build)
+-  [Register MATLAB as Jenkins Tool](#register-matlab-as-jenkins-tool)
+   -  [Use MATLAB as a Tool in Pipeline Project](#use-matlab-as-a-tool-in-pipeline-project)
 
 ## Configure Plugin in Web UI
 You can use the web UI provided by Jenkins to configure the plugin in freestyle and multi-configuration projects. To run MATLAB or Simulink in a Pipeline project, see [Set Up Pipeline Project](#set-up-pipeline-project).
@@ -33,7 +35,7 @@ If the build agent already has your desired MATLAB on the path, then you are not
 |--------------|---------------------------------|
 | Windows® | C:\Program Files\MATLAB\R2020b  |
 | Linux®   | /usr/local/MATLAB/R2020b        |
-| macOS          | /Applications/MATLAB_R2020b.app |
+| macOS        | /Applications/MATLAB_R2020b.app |
 
 ### Specify Build Steps
 When you set up the **Build** section of the project configuration window, the plugin provides you with the **Run MATLAB Command** and **Run MATLAB Tests** build steps.
@@ -55,7 +57,7 @@ Test artifacts are not autogenerated if you choose to run tests using this build
 #### Run MATLAB Tests
 This build step uses a default setting to run tests authored using the MATLAB Unit Testing Framework or Simulink Test™. If your source code is organized into files and folders within a MATLAB project, then the plugin includes any test files in the project that have been labeled as `Test`. If your code does not leverage a MATLAB project or uses a MATLAB release before R2019a, then the plugin includes all tests in the project workspace, including its subfolders.
 
-With the **Run MATLAB Tests** build step, you can optionally specify the location of folders containing source code, relative to the project root folder. When you specify a folder in the **Folder path** box, the plugin adds the specified folder and its subfolders to the top of the MATLAB search path. You can specify more folders by clicking **Add Folder**. If you specify folders, MATLAB uses only the source code in the specified folders and their subfolders to generate a coverage report. 
+With the **Run MATLAB Tests** build step, you can specify the locations of source code folders relative to the project root folder. When you specify a folder in the **Folder path** box, the plugin adds the folder and its subfolders to the top of the MATLAB search path. You can specify more folders by clicking **Add Folder**. If you specify source code folders and then choose to generate a coverage report, MATLAB uses only the code in the specified folders and their subfolders to generate the report. 
 
  ![run_matlab_tests](https://user-images.githubusercontent.com/48831250/94472880-64efe700-0199-11eb-8c2f-e733f104ba95.png)
 
@@ -119,11 +121,11 @@ When you define your Pipeline with a `Jenkinsfile`, the plugin provides you with
 
 To configure the plugin for a Pipeline project:
 1) Define your Pipeline in a `Jenkinsfile` in the root of your repository.
-2) In the **Pipeline** section of the project configuration window, select **Pipeline script from SCM** from the **Definition** drop-down menu. 
-3) Select your source control system from the **SCM** drop-down menu.
+2) In the **Pipeline** section of the project configuration window, select **Pipeline script from SCM** from the **Definition** drop-down list. 
+3) Select your source control system from the **SCM** drop-down list.
 4) Paste your repository URL into the **Repository URL** box.
 
-You also can define your Pipeline directly in the project configuration window. If you select **Pipeline script** from the **Definition** drop-down menu, you can author your Pipeline code in the **Script** box. When you define your Pipeline this way, your Pipeline must include an additional stage to check out MATLAB code from source control.
+You also can define your Pipeline directly in the project configuration window. If you select **Pipeline script** from the **Definition** drop-down list, you can author your Pipeline code in the **Script** box. When you define your Pipeline this way, your Pipeline must include an additional stage to check out MATLAB code from source control.
 
 ### Add MATLAB to System Path
 When Jenkins executes MATLAB-related steps in your Pipeline, it uses the first MATLAB version on the system path. If the PATH environment variable of the build agent does not include any MATLAB versions, you must update the variable with the MATLAB root folder that should be used for the build.
@@ -282,7 +284,7 @@ node {
 ## Use MATLAB in Matrix Build
 Similar to multi-configuration projects, you can use MATLAB as part of a [matrix](https://www.jenkins.io/doc/book/pipeline/syntax/#declarative-matrix) build in Pipeline projects. For example, you can define a Pipeline to run your test suite on different platforms or against different versions of MATLAB.
 
-This example shows how to define a Declarative Pipeline to run your MATLAB code and generate test artifacts using MATLAB R2018b, R2019a, and R2020b. The Pipeline has a `matrix` section to define the possible name-value combinations that should run in parallel. 
+This example shows how to define a Declarative Pipeline to run your MATLAB code and generate test artifacts using MATLAB R2018b, R2019a, and R2020b. The Pipeline has a `matrix` block to define the possible name-value combinations that should run in parallel. 
 
 ```groovy
 // Declarative Pipeline
@@ -321,6 +323,115 @@ pipeline {
 }
 ``` 
 
+## Register MATLAB as Jenkins Tool
+To run MATLAB code and Simulink models as part of your automated pipeline of tasks, Jenkins invokes MATLAB as an external program. When you configure your project, you can explicitly specify the MATLAB version that Jenkins should invoke by providing the path to the desired MATLAB root folder. For example, you can use an `environment` block in your `Jenkinsfile` to specify a MATLAB root folder for your Pipeline project.
+
+Instead of specifying the path to the MATLAB root folder on a per project basis, you can register MATLAB as a Jenkins tool, which can then be accessed by any project you configure in Jenkins. To register your desired MATLAB version as a tool, you are required to specify its name and location on the build agent. Once you have registered MATLAB as a tool, you no longer need to specify its root folder path within a project. Jenkins only needs the tool name to access MATLAB.
+
+To register MATLAB as a Jenkins tool:
+
+1) In your Jenkins interface, select **Manage Jenkins > Global Tool Configuration**. A new page opens where you can register different tools with Jenkins.
+2) In the **MATLAB** section of the **Global Tool Configuration** page, locate and click **Add MATLAB**. The section expands and enables you to specify the name and installation location of MATLAB.
+3) specify the name for your desired MATLAB version in the **Name** box, and enter the full path to the MATLAB root folder in the **MATLAB root** box. To register MATLAB as a tool, you are not required to select **Install automatically**. 
+4) To confirm your choices, click **Save** at the bottom of the page.
+
+For example, register MATLAB R2020b as a Jenkins tool on your Windows-based local agent.
+
+![matlab_tool](https://user-images.githubusercontent.com/48831250/98566654-0714eb80-227d-11eb-90b8-4875ab32bf66.png)
+
+If your Jenkins instance includes remote agents, you can register MATLAB as a tool on the remote agents using the tool name that you have specified on the local agent. For example, if you have registered MATLAB R2020b as a tool on your local agent, you can register the same MATLAB version installed on a remote agent as a tool on the remote agent. To register MATLAB as a Jenkins tool on a remote agent: 
+
+1) Navigate to the **Node Properties** interface of the agent. You can access this interface by selecting **Manage Jenkins > Manage Nodes and Clouds**, clicking the link corresponding to the agent, and then selecting **Configure** on the left.
+2) Select **Tool Locations**. Then, select the tool name from the **Name** drop-down list. The list contains the names assigned to the registered MATLAB versions on the local agent.  
+3) In the **Home** box, enter the full path to the MATLAB root folder on the remote agent.
+4) Click **Save** to confirm your choices.
+
+For example, on a Linux-based remote agent, register MATLAB R2020b as a tool.
+
+![tool_remote](https://user-images.githubusercontent.com/48831250/98685471-67676400-2335-11eb-9db5-bd027bc053f6.PNG)
+
+**Note:** Currently, using MATLAB as a tool is supported only for Pipeline projects.
+
+### Use MATLAB as a Tool in Pipeline Project
+To invoke MATLAB as a Jenkins tool using Declarative Pipeline syntax, use a `tools` block in your `Jenkinsfile`. To specify the tool in the block, use the `matlab` keyword followed by the name assigned to the tool on the **Global Tool Configuration** page. For example, use the MATLAB version that has been defined as a tool named R2020b to run the commands in the file `myscript.m`.  
+
+```groovy
+// Declarative Pipeline
+pipeline {
+   agent any
+   tools {
+       matlab 'R2020b'
+   }
+    stages{
+        stage('Run MATLAB Command') {
+            steps
+            {
+               runMATLABCommand 'myscript'
+            }       
+        }                
+    } 
+}
+
+```
+
+If you define your Pipeline using Scripted Pipeline syntax, use the `tool` keyword followed by the name of the tool to retrieve the path to the MATLAB root folder. Then, prepend the path to the `bin` folder of the desired MATLAB version to the PATH environment variable.
+
+```groovy
+// Scripted Pipeline
+node {
+    def matlabver
+    stage('Run MATLAB Command') {
+        matlabver = tool 'R2020b'
+        if (isUnix()){
+            env.PATH = "${matlabver}/bin:${env.PATH}"   // Linux or macOS agent
+        }else{
+            env.PATH = "${matlabver}\\bin;${env.PATH}"   // Windows agent
+        }     
+        runMATLABCommand 'myscript'
+    }
+}
+```
+You also can invoke MATLAB as a Jenkins tool when you perform a matrix build in your Pipeline project. This example shows how to use three MATLAB versions (specified in an `axis` block using their corresponding tool names) to run a set of MATLAB commands and tests. 
+
+```groovy
+// Declarative Pipeline
+pipeline {
+    agent any
+    stages {
+        stage('BuildAndTest') {
+            matrix {
+                agent any
+                axes {
+                    axis {
+                        name 'MATLAB_VERSION'
+                        values 'R2018b', 'R2019a', 'R2020b'
+                    }
+                }
+                tools{
+                    matlab "${MATLAB_VERSION}"
+                }
+                stages {
+                    stage('Run MATLAB commands') {
+                        steps {
+                            runMATLABCommand 'ver'
+                            runMATLABCommand 'pwd'
+                        }
+                    }
+                    stage('Run MATLAB Tests') {
+                    steps
+                        {
+                            runMATLABTests(testResultsJUnit: 'test-results/results.xml',
+                                           codeCoverageCobertura: 'code-coverage/coverage.xml')
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+
 ## See Also
 [Run MATLAB Tests on Jenkins Server](examples/Run-MATLAB-Tests.md)<br/>
 [Continuous Integration (MATLAB)](https://www.mathworks.com/help/matlab/continuous-integration.html)<br/>