Automate Project Tasks Using Scripts

Open Script

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")

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/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe"
                    TopLevel: 1
                    ReadOnly: 0
         DefinitionFilesType: FixedPathMultiFile
    SourceControlIntegration: "Git"
          RepositoryLocation: "/tmp/Bdoc23b_2361005_2306498/tp7de75c45/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]
         DependencyCacheFile: ""
         SimulinkCacheFolder: "/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/work/cache"
       SimulinkCodeGenFolder: "/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/work/codegen"
        ProjectStartupFolder: "/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe"

Find Project Commands

Find out what you can do with your project.

methods(proj)

Methods for class matlab.project.Project:

addFile                       listModifiedFiles             
addFolderIncludingChildFiles  listRequiredFiles             
addPath                       refreshSourceControl          
addReference                  reload                        
addShortcut                   removeCategory                
addShutdownFile               removeFile                    
addStartupFile                removePath                    
close                         removeReference               
createCategory                removeShortcut                
export                        removeShutdownFile            
findCategory                  removeStartupFile             
findFile                      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/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/lib"
               Revision: "fa63475d7038602918f31752640660c70d135004"
    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/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/AnalogControl.slx"
               Revision: "fa63475d7038602918f31752640660c70d135004"
    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/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/resources/project/uuid-01a3a421-668b-492d-9d1f-33921f2c57a6.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/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/AnalogControl.slx'}
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/data/controller.sldd'    }
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/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/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/DigitalControl.slx'}
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/LinearActuator.slx'}
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/slproject_f14.slx' }
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/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/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/vertical_channel.slx'}
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/f14_airframe.slx'    }
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/slproject_f14.slx'   }
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/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/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/data/buses.sldd'             }
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/data/controller.sldd'        }
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/data/system_model.sldd'      }
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/tests/f14_airframe_test.m'   }
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/AnalogControl.slx'    }
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/DigitalControl.slx'   }
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/LinearActuator.slx'   }
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/NonLinearActuator.slx'}
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/f14_airframe.slx'     }
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/slproject_f14.slx'    }
    {'/tmp/Bdoc23b_2361005_2306498/tp7de75c45/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/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/utilities/rebuild_s_functions.m"

Get the file path of a shortcut.

shortcuts(3).File

ans = 

    "/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/utilities/rebuild_s_functions.m"

Examine all the files in the shortcuts cell array.

{shortcuts.File}'

ans =

  3x1 cell array

    {["/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/models/slproject_f14.slx"       ]}
    {["/tmp/Bdoc23b_2361005_2306498/tp7de75c45/simulink/AirframeProjectExample/airframe/reports/slproject_f14.pdf"      ]}
    {["/tmp/Bdoc23b_2361005_2306498/tp7de75c45/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:

                Name: "Engineers"
        SingleValued: 0
            DataType: "char"
    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/Bdoc23b_2361005_2306498/tp7de75c45/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/Bdoc23b_2361005_2306498/tp7de75c45/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.