matlab.project.Project

Project object

Description

The matlab.project.Project object represents the currently loaded project. Use the project object to programmatically manipulate the project, interact with source control, and find file dependencies.

Creation

To create a matlab.project.Project object, use the currentProject function to get the currently open project. For example:

proj = currentProject;

If no project is currently open, use the openProject function to load an existing project. For example:

proj = openProject("C:/workSpace/project1/");

To create and open a blank project and get the project object, use the matlab.project.createProject function. For example:

proj = matlab.project.createProject;

Properties

Name — Project name

string scalar

Project name, specified as a string scalar.

Description — Project description

string scalar

Project description, specified as a string scalar.

RootFolder — Path of project root folder

string scalar

Path of project root folder, specified as a string scalar.

TopLevel — Project top-level status

logical

This property is read-only.

Top-level status, returned as a logical 1 (true) if the project is a top-level project.

ReadOnly — Project permission status

logical

This property is read-only.

Project permission status, returned as a logical 1 (true) if the project has limited permissions when using add, remove, and create object functions. A referenced project status is always read-only to prevent modification.

DefinitionFilesType — Project definition file types

array of DefinitionFilesType objects

Project definition file types, specified as an array of DefinitionFilesType objects. Use matlab.project.convertDefinitionFiles to change the current project definition file type programmatically.

SourceControlMessages — Source control information

string array

This property is read-only.

Source control information, specified as a string array.

Example: "Branch status: Normal" "No remote tracking branch" "Current branch: main"

RepositoryLocation — Project repository location

string scalar

This property is read-only.

Project repository location, specified as a string scalar.

SourceControlIntegration — Source control integration type

string scalar

This property is read-only.

Source control integration type, specified as a string scalar.

Example: "Git"

Files — Paths of project files

array of ProjectFile objects

Paths of project files, specified as an array of ProjectFile objects. This property changes when you add or remove project files. You can use addFile, addFolderIncludingChildFiles, or removeFile to add or remove project files.

Shortcuts — Shortcut files

array of Shortcut objects

Shortcut files for project, specified as an array of Shortcut objects. This property changes when you add or remove shortcut files. You can use addShortcut and removeShortcut to create or remove shortcut files programmatically.

Categories — Label categories

array of Category objects

Label categories for project, specified as an array of Category objects. This property changes when you create or remove label categories. You can use createCategory and removeCategory to create and remove label categories programmatically.

Dependencies — Graph of dependencies between project files

digraph object

Graph of dependencies between project files, specified as a digraph object.

StartupFiles — Project startup files

string array

Project startup files, specified as a string array. This property changes when you add or remove startup files. You can use addStartupFile and removeStartupFile to add or remove startup files programmatically.

ShutdownFiles — Project shutdown files

string array

Project shutdown files, specified as a string array. This property changes when you add or remove shutdown files. You can use addShutdownFile and removeShutdownFile to add or remove shutdown files programmatically.

ProjectPath — Project path folders

array of PathFolder objects

Project path folders that are added to the MATLAB^® path, specified as an array of PathFolder objects.

ProjectReferences — Paths of referenced projects

array of ProjectReference objects

Paths of referenced projects, specified as an array of ProjectReference objects. This property changes when you add or remove reference projects. You can use addReference and removeReference to add or remove reference projects programmatically.

ProjectStartupFolder — Project startup folder

string scalar

Path of the project startup folder, specified as a string scalar.

SimulinkCacheFolder — Path of Simulink cache folder

string scalar

Path of Simulink^® cache folder, specified as a string scalar.

SimulinkCodeGenFolder — Path of Simulink Coder code generation folder

string scalar

Path of Simulink Coder™ code generation folder, specified as a string scalar.

DependencyCacheFile — Path of dependency analysis cache file

string scalar

Path of dependency analysis cache file, specified as a string scalar.

Object Functions

Create and Export Projects

currentProject	Get current project
openProject	Load an existing project
isLoaded	Determine if project is loaded
reload	Reload project
close	Close project
export	Export project to archive
matlab.project.createProject	Create blank project
matlab.project.convertDefinitionFiles	Change definition file type of project
matlab.project.deleteProject	Stop folder management and delete project definition files
matlab.project.loadProject	Load project
matlab.project.rootProject	Get root project

Set Up Projects

addFile	Add file or folder to project
addFolderIncludingChildFiles	Add folder and child files to project
removeFile	Remove file or folder from project
addPath	Add folder to project path
removePath	Remove folder from project path
addReference	Add referenced project to project
listAllProjectReferences	List all projects in reference hierarchy of current project
removeReference	Remove project reference
addStartupFile	Add startup file to project
addShutdownFile	Add shutdown file to project
removeStartupFile	Remove startup file from project startup list
removeShutdownFile	Remove shutdown file from project shutdown list
addShortcut	Add shortcut to project
removeShortcut	Remove shortcut from project

Manage Project Files

addLabel	Attach label to project file
createLabel	Create project label
removeLabel	Remove label from project
findLabel	Get project file label
createCategory	Create category of project labels
findCategory	Find project category of labels
removeCategory	Remove project category of labels
findFile	Find single project file by name
listModifiedFiles	List modified files in project
listRequiredFiles	Get files required by specified project files
listImpactedFiles	Get files impacted by changes to specified project files
listAllProjectReferences	List all projects in reference hierarchy of current project
refreshSourceControl	Update source control status of project files
runChecks	Run all project checks
updateDependencies	Update project dependencies
matlab.project.isUnderProjectRoot	Determine whether file or folder is under project root folder
matlab.project.isFileInProject	Determine whether file or folder belongs to project

Examples

Get Times Table App Example Project

Open the Times Table App project and use currentProject to get a project object that you can manipulate programmatically.

openExample("matlab/TimesTableProjectExample")
proj = currentProject

proj = 

  Project with properties:

                        Name: "Times Table App"
    SourceControlIntegration: "Git"
          RepositoryLocation: "C:\workSpace\examples\repositories\TimesTableApp"
       SourceControlMessages: ["Branch status: Normal"    "Current branch: main"    "No remote tracking branch"]
                    ReadOnly: 0
                    TopLevel: 1
                Dependencies: [1×1 digraph]
                  Categories: [1×1 matlab.project.Category]
                       Files: [1×15 matlab.project.ProjectFile]
                   Shortcuts: [1×4 matlab.project.Shortcut]
                 ProjectPath: [1×3 matlab.project.PathFolder]
           ProjectReferences: [1×0 matlab.project.ProjectReference]
                StartupFiles: [1×0 string]
               ShutdownFiles: [1×0 string]
         DefinitionFilesType: FixedPathMultiFile
                 Description: "This example project contains the source code and tests for a simple educational app. ↵↵Use the "Project Shortcuts" toolstrip tab to find ways of getting started with this project."
                  RootFolder: "C:\workSpace\examples\TimesTableApp"
        ProjectStartupFolder: "C:\workSpace\examples\TimesTableApp"
         DependencyCacheFile: ""
       SimulinkCodeGenFolder: ""
         SimulinkCacheFolder: ""

Find Project Commands

Open the Times Table App project and create a project object.

openExample("matlab/TimesTableProjectExample")
proj = currentProject;

Find the functions that you can execute on the project object.

methods(proj)

Methods for class matlab.project.Project:

addFile                       export                        removeCategory                
addFolderIncludingChildFiles  findCategory                  removeFile                    
addPath                       findFile                      removePath                    
addReference                  isLoaded                      removeReference               
addShortcut                   listAllProjectReferences      removeShortcut                
addShutdownFile               listImpactedFiles             removeShutdownFile            
addStartupFile                listModifiedFiles             removeStartupFile             
addprop                       listRequiredFiles             runChecks                     
close                         refreshSourceControl          updateDependencies            
createCategory                reload                        

Methods of matlab.project.Project inherited from handle.                      

Examine Project Properties

Get a project object, and examine its properties.

Open the Times Table App project. Use currentProject to create a project object from the currently loaded project.

openExample("matlab/TimesTableProjectExample")
proj = currentProject;

Examine the project files.

files = proj.Files

files = 

  1×14 ProjectFile array with properties:

    Path
    Labels
    Revision
    SourceControlStatus

Examine the labels of the 13th file.

proj.Files(13).Labels

ans = 

  Label with properties:

            File: "C:\workSpace\examples\TimesTableApp\utilities\runTheseTests.m"
        DataType: 'none'
            Data: []
            Name: "Design"
    CategoryName: "Classification"

Get a particular file by name.

myfile = findFile(proj,"source/timesTableGame.m")

myfile = 

  ProjectFile with properties:

                   Path: "C:\workSpace\examples\TimesTableApp\source\timesTableGame.m"
                 Labels: [1×1 matlab.project.Label]
               Revision: ""
    SourceControlStatus: Unmodified

Find out what you can do with the file.

methods(myfile)

Methods for class matlab.project.ProjectFile:

addLabel     findLabel    removeLabel  

Version History

Introduced in R2019a