MATLAB Examples

Automate Simulink Project Tasks Using Scripts

This example shows how to use the Simulink project API to automate project tasks manipulating files, including working with modified files, dependencies, shortcuts, and labels.

Contents

Get Simulink Project at the Command Line

Open the Airframe project and use simulinkproject to get a project object to manipulate the project at the command line. You must open a project in Simulink Project to perform command-line operations on the project.

sldemo_slproject_airframe
proj = simulinkproject
Creating sandbox for project.
Created example files in "C:\slexamples\airframe21"
Initializing: Project Path
Identifying shadowed project files
Running: C:\slexamples\airframe21\utilities\set_up_project.m
Building with 'MinGW64 Compiler  C '.
MEX completed successfully.

proj = 

  ProjectManager with properties:

                 Name: 'Simulink Project Airframe Example'
          Information: [1×1 slproject.Information]
         Dependencies: [1×1 slproject.Dependencies]
            Shortcuts: [1×9 slproject.Shortcut]
          ProjectPath: [1×7 slproject.PathFolder]
    ProjectReferences: [1×0 slproject.ProjectReference]
           Categories: [1×1 slproject.Category]
                Files: [1×33 slproject.ProjectFile]
           RootFolder: 'C:\slexamples\airframe21'

Find Project Commands

Find out what you can do with your project.

methods(proj)
Methods for class slproject.ProjectManager:

addFile                       isLoaded                      
addFolderIncludingChildFiles  listModifiedFiles             
close                         refreshSourceControl          
createCategory                reload                        
export                        removeCategory                
findCategory                  removeFile                    
findFile                      
getFilesRequiredBy            

Examine Project Files

After you get a project object, you can examine project properties such as files.

files = proj.Files
files = 

  1×33 ProjectFile array with properties:

    Path
    Labels
    Revision
    SourceControlStatus

Use indexing to access files in this list. The following command gets file number 14. Each file has properties describing its path and attached labels.

proj.Files(14)
ans = 

  ProjectFile with properties:

                   Path: 'C:\slexamples\airframe21\models\AnalogControl.mdl'
                 Labels: [1×1 slproject.Label]
               Revision: '2'
    SourceControlStatus: Unmodified

Examine the labels of the 14th file.

proj.Files(14).Labels
ans = 

  Label with properties:

            File: 'C:\slexamples\airframe21\models\AnalogControl.mdl'
        DataType: 'none'
            Data: []
            Name: 'Design'
    CategoryName: 'Classification'

Get a particular file by name.

myfile = findFile(proj, 'models/AnalogControl.mdl')
myfile = 

  ProjectFile with properties:

                   Path: 'C:\slexamples\airframe21\models\AnalogControl.mdl'
                 Labels: [1×1 slproject.Label]
               Revision: '2'
    SourceControlStatus: Unmodified

Find out what you can do with the file.

methods(myfile)
Methods for class slproject.ProjectFile:

addLabel     findLabel    removeLabel  

Get Modified Files

Modify a project model file by adding an arbitrary block.

open_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 Simulink Project, where you can see a modified model file, and the corresponding .SimulinkProject definition file.

modifiedfiles = listModifiedFiles(proj)
modifiedfiles = 

  1×2 ProjectFile array with properties:

    Path
    Labels
    Revision
    SourceControlStatus

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 Simulink Project.

modifiedfiles(2)
ans = 

  ProjectFile with properties:

                   Path: 'C:\slexamples\airframe21\models\AnalogControl.mdl'
                 Labels: [1×1 slproject.Label]
               Revision: '2'
    SourceControlStatus: Modified

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 = 

  1×32 ProjectFile array with properties:

    Path
    Labels
    Revision
    SourceControlStatus

Get File Dependencies

Update the file dependencies. The project runs a dependency analysis to update the known dependencies between project files.

update(proj.Dependencies)

Examine the dependencies in the project object. The dependencies property of the project object contains the graph of dependencies between project files in a MATLAB digraph object. You can view the same dependency analysis graph in the Impact view of Simulink Project. If you want to plot the graph, instead of working with the digraph object, save the impact view to an image file.

proj.Dependencies
ans = 

  Dependencies with properties:

    Graph: [1×1 digraph]

Get the graph dependencies. You can use digraph methods to get information from the graph.

g = proj.Dependencies.Graph
g = 

  digraph with properties:

    Edges: [24×1 table]
    Nodes: [25×1 table]

Get the files required by a model.

requiredFiles = bfsearch(g, which('AnalogControl'))
requiredFiles =

  3×1 cell array

    'C:\slexamples\airframe21\models\AnalogControl.mdl'
    'C:\slexamples\airframe21\data\controller.sldd'
    'C:\slexamples\airframe21\data\buses.sldd'

Get the top-level files of all types in the graph.

top = g.Nodes.Name(indegree(g)==0);

Get the top-level files that have dependencies.

top = g.Nodes.Name(indegree(g)==0 & outdegree(g)>0)
top =

  7×1 cell array

    'C:\slexamples\airframe21\models\DigitalControl.slx'
    'C:\slexamples\airframe21\models\LinearActuator.slx'
    'C:\slexamples\airframe21\models\slproject_f14.slx'
    'C:\slexamples\airframe21\tests\f14_airframe_test.m'
    'C:\slexamples\airframe21\utilities\rebuild_s_functions.m'
    'C:\slexamples\airframe21\utilities\set_up_project.m'
    'C:\slexamples\airframe21\utilities\upgrade_project.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: [24×1 table]
    Nodes: [25×1 table]


impacted =

  4×1 cell array

    'C:\slexamples\airframe21\models\vertical_channel.slx'
    'C:\slexamples\airframe21\models\f14_airframe.slx'
    'C:\slexamples\airframe21\models\slproject_f14.slx'
    'C:\slexamples\airframe21\tests\f14_airframe_test.m'

Find files impacted by a data dictionary.

impacted2 = bfsearch(transposed, which('buses.sldd'))
impacted2 =

  11×1 cell array

    'C:\slexamples\airframe21\data\buses.sldd'
    'C:\slexamples\airframe21\data\controller.sldd'
    'C:\slexamples\airframe21\data\system_model.sldd'
    'C:\slexamples\airframe21\tests\f14_airframe_test.m'
    'C:\slexamples\airframe21\models\AnalogControl.mdl'
    'C:\slexamples\airframe21\models\DigitalControl.slx'
    'C:\slexamples\airframe21\models\f14_airframe.slx'
    'C:\slexamples\airframe21\models\LinearActuator.slx'
    'C:\slexamples\airframe21\models\NonLinearActuator.mdl'
    'C:\slexamples\airframe21\models\slproject_f14.slx'
    'C:\slexamples\airframe21\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. You can automate startup and shutdown tasks using shortcuts, or use them to save frequent tasks and frequently accessed files.

shortcuts = proj.Shortcuts
shortcuts = 

  1×9 Shortcut array with properties:

    File
    RunAtStartup
    RunAtShutdown

Examine a shortcut in the array.

shortcuts(9)
ans = 

  Shortcut with properties:

             File: 'C:\slexamples\airframe21\utilities\set_up_project.m'
     RunAtStartup: 1
    RunAtShutdown: 0

The RunAtStartup property is set to 1, so this shortcut file is set to run at project startup. At the command line, you can view but not change the RunAtStartup and RunAtShutdown properties. To set these properties, use the shortcut tools Simulink Project. Get the file path of a shortcut.

shortcuts(6).File
ans =

  1×50 char array

C:\slexamples\airframe21\reports\slproject_f14.pdf

Examine all the files in the shortcuts cell array.

{shortcuts.File}'
ans =

  9×1 cell array

    'C:\slexamples\airframe21\batch_jobs\billOfMaterials.m'
    'C:\slexamples\airframe21\batch_jobs\checkCodeProblems.m'
    'C:\slexamples\airframe21\batch_jobs\runUnitTest.m'
    'C:\slexamples\airframe21\batch_jobs\saveModelFiles.m'
    'C:\slexamples\airframe21\models\slproject_f14.slx'
    'C:\slexamples\airframe21\reports\slproject_f14.pdf'
    'C:\slexamples\airframe21\utilities\clean_up_project.m'
    'C:\slexamples\airframe21\utilities\rebuild_s_functions.m'
    'C:\slexamples\airframe21\utilities\set_up_project.m'

Create a logical array that shows the shortcuts set to run at startup.

idx = [shortcuts.RunAtStartup]
idx =

  1×9 logical array

   0   0   0   0   0   0   0   0   1

Use the logical array to get only the startup shortcuts.

startupshortcuts = shortcuts(idx)
startupshortcuts = 

  Shortcut with properties:

             File: 'C:\slexamples\airframe21\utilities\set_up_project.m'
     RunAtStartup: 1
    RunAtShutdown: 0

Get the path of the startup shortcut by accessing the File property.

startupshortcuts.File
ans =

  1×51 char array

C:\slexamples\airframe21\utilities\set_up_project.m

Label files

Create a new category of labels, of type char. In Simulink 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: [1×0 slproject.LabelDefinition]

Find out what you can do with the new category.

category = findCategory(proj, 'Engineers');
methods(category)
Methods for class slproject.Category:

createLabel  findLabel    removeLabel  

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 Simulink 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: 'C:\slexamples\airframe21\models\AnalogControl.mdl'
        DataType: 'char'
            Data: 'Please assess'
            Name: 'Bob'
    CategoryName: 'Engineers'

You can specify a variable for the label data, for example:

mydata = label.Data
mydata =

  1×13 char array

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: 'C:\slexamples\airframe21\models\AnalogControl.mdl'
        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 Simulink Project tool. For example, the project runs shutdown scripts ad checks for unsaved models.

close(proj)
Running: C:\slexamples\airframe21\utilities\clean_up_project.m
Closing Project Models
Clearing: Project Path

More Information

For more details on using the API, enter: doc simulinkproject.

To automate start and shutdown tasks, see docid:simulink_ug.btce77n.