Automate Project Tasks Using Scripts
This example shows how to use the project API to automate project tasks manipulating files, including working with modified files, dependencies, shortcuts, and labels.
Open Project
Open the Airframe example project.
openExample("simulink/AirframeProjectExample")
Starting: Simulink Building with 'gcc'. MEX completed successfully.
Get Project at the Command Line
Use currentProject to get a project object to manipulate the project at the command line.
proj = currentProject
proj = Project with properties: Name: "Airframe Example" Description: "This is an example project...." RootFolder: "/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe" TopLevel: 1 ReadOnly: 0 DefinitionFilesType: FixedPathMultiFile SourceControlIntegration: "Git" RepositoryLocation: "/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/repositories/AirframeProjectExample" SourceControlMessages: ["Current branch: main" ... ] (1x3 string) Files: [1x30 matlab.project.ProjectFile] Shortcuts: [1x3 matlab.project.Shortcut] Categories: [1x1 matlab.project.Category] Dependencies: [1x1 digraph] StartupFiles: [1x0 string] ShutdownFiles: [1x0 string] ProjectPath: [1x7 matlab.project.PathFolder] ProjectReferences: [1x0 matlab.project.ProjectReference] ProjectStartupFolder: "/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe" DependencyCacheFile: "" SimulinkCacheFolder: "/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/work/cache" SimulinkCodeGenFolder: "/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/work/codegen"
Find Project Commands
Find out what you can do with your project.
methods(proj)
Methods for class matlab.project.Project: addFile listModifiedFiles addFolderIncludingChildFiles listRequiredFiles addLabel refreshSourceControl addPath reload addReference removeCategory addShortcut removeFile addShutdownFile removeLabel addStartupFile removePath close removeReference createCategory removeShortcut export removeShutdownFile findCategory removeStartupFile findFiles runChecks isLoaded updateDependencies listAllProjectReferences listImpactedFiles Call "methods('handle')" for methods of matlab.project.Project inherited from handle.
Examine Project Files
After you get a project object, you can examine project properties such as files.
files = proj.Files
files = 1x30 ProjectFile array with properties: Path Revision SourceControlStatus Labels
Use indexing to access files in this list. The following command gets file number 10. Each file has properties describing its path and attached labels.
proj.Files(10)
ans = ProjectFile with properties: Path: "/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/lib" Revision: "e09c0eb46790261a8f13016e0c872a3ff51e6b45" SourceControlStatus: NotUnderSourceControl Labels: [1x0 matlab.project.Label]
Examine the labels of the 10th file.
proj.Files(10).Labels
ans = 1x0 Label array with properties: File DataType Data Name CategoryName
Get a particular file by name.
myfile = findFile(proj, 'models/AnalogControl.slx')
myfile = ProjectFile with properties: Path: "/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/AnalogControl.slx" Revision: "e09c0eb46790261a8f13016e0c872a3ff51e6b45" SourceControlStatus: Unmodified Labels: [1x1 matlab.project.Label]
Find out what you can do with the file.
methods(myfile)
Methods for class matlab.project.ProjectFile: addLabel findLabel removeLabel Call "methods('handle')" for methods of matlab.project.ProjectFile inherited from handle.
Get Modified Files
Modify a project model file by adding an arbitrary block.
load_system('AnalogControl') add_block('built-in/SubSystem', 'AnalogControl/test') save_system('AnalogControl')
Get all the modified files in the project. Observe two modified files. Compare with the Modified Files view in Project, where you can see a modified model file, and the corresponding project definition file.
modifiedfiles = listModifiedFiles(proj)
modifiedfiles = 1x2 ProjectFile array with properties: Path Revision SourceControlStatus Labels
Get the second modified file. Observe the file SourceControlStatus
property is Modified. Similarly, listModifiedFiles
returns any files that are added, conflicted, deleted, etc., that show up in the Modified Files view in Project.
modifiedfiles(2)
ans = ProjectFile with properties: Path: "/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/resources/project/uuid-7848ac42-f860-4922-b2c8-fa863314cb71.xml" Revision: "" SourceControlStatus: Added
Refresh source control status before querying individual files. You do not need to do before using listModifiedFiles
.
refreshSourceControl(proj)
Get all the project files with a particular source control status. For example, get the files that are Unmodified
.
proj.Files(ismember([proj.Files.SourceControlStatus], matlab.sourcecontrol.Status.Unmodified))
ans = 1x21 ProjectFile array with properties: Path Revision SourceControlStatus Labels
Get File Dependencies
Update the file dependencies. The project runs a dependency analysis to update the known dependencies between project files.
updateDependencies(proj)
Get the list of dependencies in the Airframe project. The Dependencies property contains the graph of dependencies between project files, stored as a MATLAB® digraph object.
g = proj.Dependencies
g = digraph with properties: Edges: [21x1 table] Nodes: [21x1 table]
Get the files required by a model.
requiredFiles = bfsearch(g, which('AnalogControl'))
requiredFiles = 3x1 cell array {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/AnalogControl.slx'} {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/data/controller.sldd' } {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/data/buses.sldd' }
Get the top-level files of all types in the graph.
g.Nodes.Name(indegree(g)==0);
Get the top-level files that have dependencies.
g.Nodes.Name(indegree(g)==0 & outdegree(g)>0)
ans = 4x1 cell array {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/DigitalControl.slx'} {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/LinearActuator.slx'} {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/slproject_f14.slx' } {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/tests/f14_airframe_test.m'}
Find impacted (or "upstream") files by creating a transposed graph.
transposed = flipedge(g)
impacted = bfsearch(transposed, which('vertical_channel'))
transposed = digraph with properties: Edges: [21x1 table] Nodes: [21x1 table] impacted = 4x1 cell array {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/vertical_channel.slx'} {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/f14_airframe.slx' } {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/slproject_f14.slx' } {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/tests/f14_airframe_test.m' }
Find files impacted by a data dictionary.
impacted2 = bfsearch(transposed, which('buses.sldd'))
impacted2 = 11x1 cell array {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/data/buses.sldd' } {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/data/controller.sldd' } {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/data/system_model.sldd' } {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/tests/f14_airframe_test.m' } {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/AnalogControl.slx' } {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/DigitalControl.slx' } {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/LinearActuator.slx' } {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/NonLinearActuator.slx'} {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/f14_airframe.slx' } {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/slproject_f14.slx' } {'/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/vertical_channel.slx' }
Get information on your files, such as the number of dependencies and orphans.
averageNumDependencies = mean(outdegree(g)); numberOfOrphans = sum(indegree(g)+outdegree(g)==0);
If you want to make changes to a model hierarchy, starting from the bottom up, find the topological order.
ordered = g.Nodes.Name(flip(toposort(g)));
Query Shortcuts
Examine the project's Shortcuts property.
shortcuts = proj.Shortcuts
shortcuts = 1x3 Shortcut array with properties: Name Group File
Examine a shortcut in the array.
shortcuts(3)
ans = Shortcut with properties: Name: "Rebuild Project's S-functions" Group: "Utility" File: "/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/utilities/rebuild_s_functions.m"
Get the file path of a shortcut.
shortcuts(3).File
ans = "/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/utilities/rebuild_s_functions.m"
Examine all the files in the shortcuts cell array.
{shortcuts.File}'
ans = 3x1 cell array {["/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/slproject_f14.slx" ]} {["/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/reports/slproject_f14.pdf" ]} {["/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/utilities/rebuild_s_functions.m"]}
Label files
Create a new category of labels, of type char. In the Project, the new Engineers category appears in the Labels pane.
createCategory(proj, 'Engineers', 'char')
ans = Category with properties: SingleValued: 0 DataType: "char" Name: "Engineers" LabelDefinitions: [1x0 matlab.project.LabelDefinition]
Find out what you can do with the new category.
category = findCategory(proj, 'Engineers');
methods(category)
Methods for class matlab.project.Category: createLabel findLabel removeLabel Call "methods('handle')" for methods of matlab.project.Category inherited from handle.
Define a new label in the new category.
createLabel(category, 'Bob');
Get a label definition.
ld = findLabel(category, 'Bob')
ld = LabelDefinition with properties: Name: "Bob" CategoryName: "Engineers"
Attach a label to the retrieved file, myfile. If you select the file in Project, you can see this label in the label editor pane.
addLabel(myfile, 'Engineers', 'Bob');
Get a particular label and attach data to it, for example, some text.
label = findLabel(myfile, 'Engineers', 'Bob'); label.Data = 'Please assess'
label = Label with properties: File: "/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/AnalogControl.slx" DataType: "char" Data: 'Please assess' Name: "Bob" CategoryName: "Engineers"
You can specify a variable for the label data, for example:
mydata = label.Data
mydata = 'Please assess'
Create a new label category with numeric data type.
createCategory(proj, 'Assessors', 'double'); category = findCategory(proj, 'Assessors'); createLabel(category, 'Sam');
Attach the new label to a specified file and assign data value 2 to the label.
myfile = proj.Files(14); addLabel(myfile, 'Assessors', 'Sam', 2)
ans = Label with properties: File: "/tmp/Bdoc24b_2679053_1130160/tp0bbfc9d1/simulink/AirframeProjectExample/airframe/models/AnalogControl.slx" DataType: "double" Data: 2 Name: "Sam" CategoryName: "Assessors"
Close Project
Closing the project at the command line is the same as closing the project using the Project tool. For example, the project runs shutdown scripts ad checks for unsaved models.
close(proj)
More Information
For more details on using the API, enter: doc currentProject
.
To automate start and shutdown tasks, see Automate Startup Tasks.
See Also
currentProject
| listModifiedFiles
| refreshSourceControl
| addLabel
| createLabel