From d6ec7c26e09a786c0cde92f1b2e14a3ebc462ae3 Mon Sep 17 00:00:00 2001 From: David Buzinski <103441853+davidbuzinski@users.noreply.github.com> Date: Wed, 20 Mar 2024 10:47:13 -0400 Subject: [PATCH] Update doc to match editor reviewed doc (#69) --- src/@orb.yml | 2 +- src/commands/install.yml | 14 +-- src/commands/run-build.yml | 18 ++-- src/commands/run-command.yml | 21 ++--- src/commands/run-tests.yml | 120 +++++++++++++------------ src/examples/run-build.yml | 4 +- src/examples/run-custom-script.yml | 4 +- src/examples/run-tests-with-report.yml | 4 +- 8 files changed, 101 insertions(+), 86 deletions(-) diff --git a/src/@orb.yml b/src/@orb.yml index 3dd6d5f..d090fcf 100644 --- a/src/@orb.yml +++ b/src/@orb.yml @@ -1,7 +1,7 @@ version: 2.1 description: > - Run MATLAB and Simulink as part of your build pipeline. + Run MATLAB as part of your build pipeline. display: source_url: https://github.com/mathworks/matlab-circleci-orb diff --git a/src/commands/install.yml b/src/commands/install.yml index ca50e92..dee1897 100644 --- a/src/commands/install.yml +++ b/src/commands/install.yml @@ -1,21 +1,23 @@ description: > - Install a specific version of MATLAB. (If you use this command to install transformation products, - such as MATLAB Coder and MATLAB Compiler, the command does not automatically license such products for you.) + Install a specific release of MATLAB. If you do not specify a release, the command installs the latest + release of MATLAB. As part of the installation process, the command prepends MATLAB to the `PATH` system + environment variable. parameters: products: description: > Products to install in addition to MATLAB, specified as a list of product names separated by spaces. You can specify this parameter to install most MathWorks products and support packages. The - command uses MATLAB Package Manager (`mpm`) to install products. For a list of supported - products and their correctly formatted names, see + command uses MATLAB Package Manager (`mpm`) to install products. If you use this parameter to install + transformation products, such as MATLAB Coder and MATLAB Compiler, the command does not automatically + license such products for you. For a list of supported products and their correctly formatted names, see https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md#product-installation-options. type: string default: '' release: description: > - MATLAB release to install. You can specify R2021a or a later release. By default, the value of `release` - is `latest`. If you do not specify `release`, the command installs the latest release of MATLAB. + MATLAB release to install. You can specify R2021a or a later release. If you do not specify `release`, + the command installs the latest release of MATLAB. type: string default: 'latest' no-output-timeout: diff --git a/src/commands/run-build.yml b/src/commands/run-build.yml index 9d9b208..754152c 100644 --- a/src/commands/run-build.yml +++ b/src/commands/run-build.yml @@ -1,13 +1,16 @@ description: > - Run builds using the MATLAB build tool. Use this command to run the tasks in the plan returned - by a file named buildfile.m in the root of your repository. To use the run-build command, you - need MATLAB R2022b or a later release. + Run a build using the MATLAB build tool. Use this command to run the tasks specified in a file + named `buildfile.m` in the root of your repository. To use the `run-build` command, you need MATLAB + R2022b or a later release. parameters: tasks: description: > - Space-separated list of tasks to run. If not specified, the command runs the default tasks - in the plan returned by buildfile.m as well as all the tasks on which they depend. + Tasks to run, specified as a list of task names separated by spaces. If a task accepts arguments, + enclose them in parentheses. If you do not specify `tasks`, the command runs the default tasks in + `buildfile.m` as well as all the tasks on which they depend. MATLAB exits with exit code 0 if the + tasks run without error. Otherwise, MATLAB terminates with a nonzero exit code, which causes the + command to fail. type: string default: "" build-options: @@ -20,8 +23,9 @@ parameters: default: "" startup-options: description: > - MATLAB startup options. If you specify more than one option, use a space to - separate the options. + MATLAB startup options, specified as a list of options separated by spaces. For more + information about startup options, see + https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html. type: string default: "" no-output-timeout: diff --git a/src/commands/run-command.yml b/src/commands/run-command.yml index 545e950..5882a42 100644 --- a/src/commands/run-command.yml +++ b/src/commands/run-command.yml @@ -1,21 +1,22 @@ description: > - Execute a MATLAB script, function, or statement. MATLAB exits with exit code 0 if the specified - script, function, or statement executes successfully without error. Otherwise, MATLAB terminates - with a nonzero exit code, which causes the build to fail. You can use the assert or error - functions in the command to ensure that builds fail when necessary. When you use this command, - all of the required files must be on the MATLAB search path. + Run MATLAB scripts, functions, and statements. When you use this command, all of the required + files must be on the MATLAB search path. parameters: command: description: > - Script, function, or statement to execute. If the value of command is the name of a MATLAB - script or function, do not specify the file extension. If you specify more than one MATLAB - command, use a comma or semicolon to separate the commands. + Script, function, or statement to execute. If the value of `command` is the name of a MATLAB + script or function, do not specify the file extension. If you specify more than one script, + function, or statement, use a comma or semicolon to separate them. MATLAB exits with exit + code 0 if the specified script, function, or statement executes successfully without error. + Otherwise, MATLAB terminates with a nonzero exit code, which causes the command to fail. + To fail the command in certain conditions, use the `assert` or `error` function. type: string startup-options: description: > - MATLAB startup options. If you specify more than one option, use a space to - separate the options. + MATLAB startup options, specified as a list of options separated by spaces. For more + information about startup options, see + https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html. type: string default: "" no-output-timeout: diff --git a/src/commands/run-tests.yml b/src/commands/run-tests.yml index 657559b..2bc633d 100644 --- a/src/commands/run-tests.yml +++ b/src/commands/run-tests.yml @@ -1,105 +1,113 @@ description: > - Run all tests in a MATLAB project and generate test artifacts. MATLAB includes any files in your - project that have a Test label. If your pipeline does not leverage a MATLAB project, then MATLAB - includes all tests in the the root of your repository including its subfolders. + Run MATLAB and Simulink tests and generate artifacts. By default, the command includes any files + in your project that have a `Test` label. If your pipeline does not use a MATLAB project, or if + it uses a MATLAB release before R2019a, then the command includes all tests in the root of your + repository and in any of its subfolders. The command fails if any of the included tests fails. parameters: - test-results-junit: + source-folder: description: > - Path to write test results report in JUnit XML format. + Location of the folder containing source code, relative to the project root folder. The + specified folder and its subfolders are added to the top of the MATLAB search path. If + you specify `source-folder` and then generate a coverage report, MATLAB uses only the source + code in the specified folder and its subfolders to generate the report. You can specify multiple + folders using a colon-separated or semicolon-separated list. type: string default: '' - code-coverage-cobertura: + select-by-folder: description: > - Path to write code coverage report in Cobertura XML format. + Location of the folder used to select test suite elements, relative to the project root folder. + To create a test suite, MATLAB uses only the tests in the specified folder and its subfolders. + You can specify multiple folders using a colon-separated or semicolon-separated list. type: string default: '' - code-coverage-html: + select-by-tag: description: > - Path to write code coverage report in HTML format. + Test tag used to select test suite elements. To create a test suite, MATLAB uses only the test elements + with the specified tag. type: string default: '' - source-folder: + strict: description: > - Location of the folder containing source code, relative to the project root folder. The - specified folder and its subfolders are added to the top of the MATLAB search path. To - generate a code coverage report, MATLAB uses only the source code in the specified folder and - its subfolders. You can specify multiple folders using a colon-separated or a - semicolon-separated list. - type: string - default: '' - select-by-folder: + Option to apply strict checks when running tests, specified as `false` or `true`. If you specify + a value of `true`, the command generates a qualification failure whenever a test issues a warning. + type: boolean + default: false + use-parallel: description: > - Location of the folder used to select test suite elements, relative to the project root folder. - To generate a test suite, MATLAB uses only the tests in the specified folder and its subfolders. - You can specify multiple folders using a colon-separated or a semicolon-separated list. + Option to run tests in parallel, specified as `false` or `true`. If the test runner configuration + is suited for parallelization, you can specify a value of `true` to run tests in parallel. This + parameter requires a Parallel Computing Toolbox license. + type: boolean + default: false + output-detail: + description: > + Amount of event detail displayed for the test run, specified as `none`, `terse`, `concise`, `detailed`, + or `verbose`. By default, the command displays failing and logged events at the `detailed` level and test + run progress at the `concise` level. type: string default: '' - select-by-tag: + logging-level: description: > - Test tag used to select test suite elements. To generate a test suite, MATLAB uses only the test elements - with the specified tag. + Maximum verbosity level for logged diagnostics included for the test run, specified as `none`, `terse`, + `concise`, `detailed`, or `verbose`. By default, the command includes diagnostics logged at the `terse` level. type: string default: '' - model-coverage-cobertura: + test-results-pdf: description: > - Path to write model coverage report in Cobertura XML format. + Path to write the test results in PDF format. On macOS platforms, this parameter is supported in MATLAB R2020b and later. type: string default: '' - model-coverage-html: + test-results-junit: description: > - Path to write model coverage report in HTML format. + Path to write the test results in JUnit-style XML format. type: string default: '' test-results-simulink-test: description: > - Path to export Simulink Test Manager results in MLDATX format. + Path to export Simulink Test Manager results in MLDATX format. This parameter requires a Simulink Test license, and + is supported in MATLAB R2019a and later. type: string default: '' test-results-html: description: > - Path to write test results report in HTML format. + Path to write the test results in HTML format. type: string default: '' - test-results-pdf: + code-coverage-cobertura: description: > - Path to write test results report in PDF format. + Path to write the code coverage results in Cobertura XML format. type: string default: '' - no-output-timeout: + code-coverage-html: description: > - Elapsed time the tests can run without output. The string is a decimal with unit suffix, - such as “20m”, “1.25h”, “5s”. The default is 10 minutes and the maximum is governed by the - maximum time a job is allowed to run. + Path to write the code coverage results in HTML format. type: string - default: 10m - strict: - description: > - Whether to apply strict checks when running the tests. For example, the command generates a - qualification failure if a test issues a warning. - type: boolean - default: false - use-parallel: - description: > - Whether to run tests in parallel (requires Parallel Computing Toolbox). This feature might - not be compatible with certain arguments, in which case, tests run in serial regardless of - the specified value. - type: boolean - default: false - output-detail: + default: '' + model-coverage-cobertura: description: > - Display level for event details produced by the test run, specified as 'None', 'Terse', 'Concise', 'Detailed', or 'Verbose'. + Path to write the model coverage results in Cobertura XML format. This parameter requires a Simulink Coverage license, + and is supported in MATLAB R2018b and later. type: string default: '' - logging-level: + model-coverage-html: description: > - Maximum verbosity level for logged diagnostics included for the test run, specified as 'None', 'Terse', 'Concise', 'Detailed', or 'Verbose'. + Path to write the model coverage results in HTML format. This parameter requires a Simulink Coverage license, and is + supported in MATLAB R2018b and later. type: string default: '' + no-output-timeout: + description: > + Elapsed time the tests can run without output. The string is a decimal with unit suffix, + such as “20m”, “1.25h”, “5s”. The default is 10 minutes and the maximum is governed by the + maximum time a job is allowed to run. + type: string + default: 10m startup-options: description: > - MATLAB startup options. If you specify more than one option, use a space to - separate the options. + MATLAB startup options, specified as a list of options separated by spaces. For more + information about startup options, see + https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html. type: string default: "" diff --git a/src/examples/run-build.yml b/src/examples/run-build.yml index 9f324ff..7389af5 100644 --- a/src/examples/run-build.yml +++ b/src/examples/run-build.yml @@ -1,5 +1,5 @@ description: > - Run a MATLAB build for your project. + Run a build using the MATLAB build tool. usage: version: 2.1 @@ -8,7 +8,7 @@ usage: jobs: build: machine: - image: ubuntu-2204:2022.07.1 + image: ubuntu-2204:2024.01.1 steps: - checkout - matlab/install diff --git a/src/examples/run-custom-script.yml b/src/examples/run-custom-script.yml index 9503719..f80cddf 100644 --- a/src/examples/run-custom-script.yml +++ b/src/examples/run-custom-script.yml @@ -1,5 +1,5 @@ description: > - Run a custom MATLAB script in your project. + Run a MATLAB script in your project. usage: version: 2.1 @@ -8,7 +8,7 @@ usage: jobs: build: machine: - image: ubuntu-2204:2022.07.1 + image: ubuntu-2204:2024.01.1 steps: - checkout - matlab/install diff --git a/src/examples/run-tests-with-report.yml b/src/examples/run-tests-with-report.yml index ee0cc8c..66c4d0a 100644 --- a/src/examples/run-tests-with-report.yml +++ b/src/examples/run-tests-with-report.yml @@ -1,5 +1,5 @@ description: > - Run all tests in your project and produce a test results report. + Run all tests in your project and produce test results in JUnit-style XML format. usage: version: 2.1 @@ -8,7 +8,7 @@ usage: jobs: build: machine: - image: ubuntu-2204:2022.07.1 + image: ubuntu-2204:2024.01.1 steps: - checkout # Install Simulink and Simulink Test in addition to MATLAB