Running Custom Tasks with a Project
This example shows how to apply a custom task to a set of files managed by project. The example custom task analyzes the Simulink models which are in the project, reporting the number of blocks in each model.
Setting Up the Example Files and Opening Project
1. Run the following commands to create and open a working copy of the "sldemo_slproject_airframe" example.
sldemo_slproject_airframe;
Building with 'MinGW64 Compiler (C)'. MEX completed successfully.
The project example copies files to a new folder so that you can edit them and put them under local version control.
Select a Custom Task
2. Click the Custom Task button in the Tools section of the project toolstrip tab.
You define a custom task with a MATLAB® function. The example Airframe project contains example custom tasks in the custom_tasks folder.
3. The "Custom Task" menu lists available custom tasks.
To view, edit, and create custom tasks, click Custom Tasks > Manage Custom Tasks in the Tools section of the Project toolstrip tab.
4. Select the 'Analyze Model Files' custom task.
The function name of your selected custom task appears in the "Custom task" edit box. The example analyzeModelFiles adds a label from the category "Metrics" to each model file in the project. Labels in this category have numerical data. The custom task will count the number of blocks in each model and attach this number to the label.
Select Files to Include in the Custom Task
5. In the Custom Task dialog box, verify that all model files have selected check boxes in the Include column.
Running a Custom Task
6. Click the Run Task button on the bottom right of the Custom Task dialog box.
The results for a selected file are also shown in the Results pane at the bottom of the dialog box. This can be useful when the results returned are long, or contain HTML markup.
The following example shows the dialog box after running the custom task on some models. You can customize the columns to show with the "cog" icon Actions button at the top right.
Editing an Existing Custom Task
Custom Tasks are MATLAB functions. Edit your custom task with the MATLAB editor. In the following steps, you modify the custom task to use the project API to add a label with data, as well as saving any dirty model files.
7. Run the following MATLAB code to create a Metrics category and a Block Count label in the project.
project = currentProject; category = createCategory(project, 'Metrics', 'double');
8. Double-click analyzeModelFiles.m (or right-click and select Open) to edit it in the MATLAB editor.
9. Add the following lines just after the sprintf command:
[~, compileStats] = sldiagnostics(name, 'CompileStats'); addLabel(projectFile, 'Metrics', 'CPU Compile Time', sum([compileStats.Statistics.CPUTime]));
You can use the MATLAB editor to set breakpoints and debug a custom task function, just as with any other MATLAB function.
If you rerun the custom task, it adds the CPU Compile Time label to each model file that can be compiled, and attaches data to the label showing the total time for all compilation phases for the model. Models that cannot be compiled show "Failed to analyze file" in the Custom Task Report, and details display as a warning in the command window. Examine the custom task analyzeModelFiles.m to see how to handle errors.
To view the new metrics data, either show the Metrics column in the Custom Task Report, or look in the project files view.
Creating a New Custom Task
Create a new custom task by creating a new MATLAB function. Your custom tasks must:
Be saved on the MATLAB path.
Accept a single input argument: a full path to a file.
Return a single output argument.
To create custom tasks, click Custom Tasks > Manage Custom Tasks in the Tools section of the project toolstrip tab. In the Manage Custom Tasks dialog box, click Add to open a new file with instructions that guide you to create a custom task with the correct function signature.
10. Click "Add" and select the "Add Using New Script" menu item.
A file dialog opens asking you to choose where to create the new custom task. The custom task must be saved on the MATLAB path to run.
11. Provide a file name and save the file in the 'custom_tasks' folder within the project.
The MATLAB editor opens the file pre-populated with a simple example custom task.
12. To create your new custom task, edit the contents of the example custom task function and save.