Create and Edit Projects Programmatically
This example shows how to use the command line to automate project tasks for manipulating files. The example covers how to create a referenced project from existing project files, set up the project path, and define project shortcuts. It also shows how to work with modified files, dependencies, and labels.
Open Project
The Times Table App example project is under Git™ source control. To create a project object, use currentProject
or openProject
.
mainProject = openProject("TimesTableApp");
To check for project startup issues, use the listStartupIssues
function.
startupIssues = listStartupIssues(mainProject)
startupIssues = 1×0 Issue array with properties: ID Details ProblemFiles ProjectRoot Exception
Examine Project Files
Examine the files in the project.
files = mainProject.Files
files=1×13 ProjectFile array with properties:
Path
Revision
SourceControlStatus
Labels
Use indexing to access files in this list. For example, get file number 9. Each file has properties describing its path and attached labels.
mainProject.Files(9)
ans = ProjectFile with properties: Path: "/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/tests/tNewTimesTable.m" Revision: "a337f9918f5b73b8a5d376e70b77c210ea0f1cf2" SourceControlStatus: Unknown Labels: [1×1 matlab.project.Label]
Get Git latest revision of the file number 9.
mainProject.Files(9).Revision
ans = "a337f9918f5b73b8a5d376e70b77c210ea0f1cf2"
Examine the labels of the file number 9.
mainProject.Files(9).Labels
ans = Label with properties: File: "/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/tests/tNewTimesTable.m" DataType: "none" Data: [] Name: "Test" CategoryName: "Classification"
Get a particular file by name.
myfile = findFiles(mainProject,"source/timestable.mlapp",OutputFormat="ProjectFile")
myfile = ProjectFile with properties: Path: "/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/source/timestable.mlapp" Revision: "a337f9918f5b73b8a5d376e70b77c210ea0f1cf2" SourceControlStatus: Unmodified Labels: [1×1 matlab.project.Label]
Create New Project
Create the Times Table Game project. This project will store the game logic behind the Times Table App. The Times Table Game project will be used by the Times Table App project through a project reference.
Create the project and set the project name.
timesTableGameFolder = fullfile(mainProject.RootFolder,"refs","TimesTableGame"); timesTableGame = matlab.project.createProject(timesTableGameFolder); timesTableGame.Name = "Times Table Game";
Move the Times Table App game logic from the main project folder to the new project folder, and add it to the Times Table Game project. Then, remove the file from the Times Table App project.
movefile("../../source/timesTableGame.m"); addFile(timesTableGame,"timesTableGame.m"); reload(mainProject); removeFile(mainProject,"source/timesTableGame.m");
Add the Times Table Game project root folder to the Times Table Game project path. This makes the timesTableGame.m
file available when the Times Table App project or any project that references the Times Table App project is loaded.
reload(timesTableGame); addPath(timesTableGame,timesTableGame.RootFolder);
Add a Project Reference
Add the new Times Table Game project to the Times Table App project as a project reference. This allows the Time Table App project to view, edit, and run files in the Times Table Game project.
reload(mainProject); addReference(mainProject,timesTableGame);
Get Modified Files
Get all the modified files in the Times Table App project. Compare this list with the Modified Files section in the Source Control panel. If the Source Control icon is not in the sidebar, click the Open more panels button and add it.
You can see the files for the new Times Table Game project, as well as the removed and modified files in the Times Table App project.
modifiedfiles = listModifiedFiles(mainProject)
modifiedfiles=1×3 ProjectFile array with properties:
Path
Revision
SourceControlStatus
Labels
Get the second modified file in the list. Observe that the SourceControlStatus
property is Added
. The listModifiedFiles
function returns any files that are added, modified, conflicted, deleted, and so on.
modifiedfiles(2)
ans = ProjectFile with properties: Path: "/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/resources/project/LUgSFhI3RPozNzNcutxrczVe6f0/DIWK6i5dwjl8vGqz0busHOwsZxUd.xml" Revision: "" SourceControlStatus: Added
Refresh the source control status before querying individual files. You do not need to do this before calling listModifiedFiles
.
refreshSourceControl(mainProject)
Get all the project files that are Unmodified
. Use the ismember
function to get an array of logicals stating which files in the Times Table App project are unmodified. Use the array to get the list of unmodified files.
unmodifiedStatus = ismember([mainProject.Files.SourceControlStatus],matlab.sourcecontrol.Status.Unmodified); mainProject.Files(unmodifiedStatus)
ans=1×8 ProjectFile array with properties:
Path
Revision
SourceControlStatus
Labels
Get File Dependencies
Run a dependency analysis to update the known dependencies between project files.
updateDependencies(mainProject)
Get the list of dependencies in the Times Table App project. The Dependencies
property contains the graph of dependencies between project files, stored as a MATLAB digraph
object.
g = mainProject.Dependencies
g = digraph with properties: Edges: [2×1 table] Nodes: [8×1 table]
Get the files required by the timestable.mlapp
file.
requiredFiles = bfsearch(g, which("source/timestable.mlapp"))
requiredFiles = 1×1 cell array
{'/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/source/timestable.mlapp'}
Get the top-level files of all types in the graph. The indegree
function finds all the files that are not depended on by any other file.
top = g.Nodes.Name(indegree(g)==0)
top = 7×1 cell
{'/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/requirements/TimesTableRequirements.mlx'}
{'/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/tests/tAnswerIsCorrect.m' }
{'/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/tests/tCurrentQuestion.m' }
{'/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/tests/tNewTimesTable.m' }
{'/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/utilities/editTimesTable.m' }
{'/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/utilities/openRequirementsDocument.m' }
{'/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/utilities/runTheseTests.m' }
Get the top-level files that have dependencies. The indegree
function finds all the files that are not depended on by any other file, and the outdegree
function finds all the files that have dependencies.
top = g.Nodes.Name(indegree(g)==0 & outdegree(g)>0)
top = 2×1 cell
{'/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/requirements/TimesTableRequirements.mlx'}
{'/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/utilities/editTimesTable.m' }
Find impacted (or "upstream") files by creating a transposed graph. Use the flipedge
function to reverse the direction of the edges in the graph.
transposed = flipedge(g)
transposed = digraph with properties: Edges: [2×1 table] Nodes: [8×1 table]
impacted = bfsearch(transposed,which("source/timestable.mlapp"))
impacted = 3×1 cell
{'/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/source/timestable.mlapp' }
{'/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/requirements/TimesTableRequirements.mlx'}
{'/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/utilities/editTimesTable.m' }
Get information on the project files, such as the number of dependencies and orphans.
averageNumDependencies = mean(outdegree(g)); numberOfOrphans = sum(indegree(g)+outdegree(g)==0);
Change the sort order of the dependency graph to show project changes from the bottom up.
ordered = g.Nodes.Name(flip(toposort(g)));
Query Shortcuts
You can use shortcuts to save frequent tasks and frequently accessed files, or to automate startup and shutdown tasks.
Get the Times Table App project shortcuts.
shortcuts = mainProject.Shortcuts
shortcuts=1×4 Shortcut array with properties:
Name
Group
File
Examine a shortcut in the list.
shortcuts(2)
ans = Shortcut with properties: Name: "Edit Times Table App" Group: "Launch Points" File: "/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/utilities/editTimesTable.m"
Get the file path of a shortcut.
shortcuts(3).File
ans = "/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/utilities/openRequirementsDocument.m"
Examine all the files in the shortcuts list.
{shortcuts.File}'
ans=4×1 cell array
{["/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/source/timestable.mlapp" ]}
{["/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/utilities/editTimesTable.m" ]}
{["/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/utilities/openRequirementsDocument.m"]}
{["/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/utilities/runTheseTests.m" ]}
Label Files
Create a new category of labels of type char
.
To see all labels and label categories in the Times Table App project, in the Project toolstrip, click Settings. In the Labels section, you see the built-in labels and the new Engineers
category.
createCategory(mainProject,"Engineers","char")
ans = Category with properties: SingleValued: 0 DataType: "char" Name: "Engineers" LabelDefinitions: [1×0 matlab.project.LabelDefinition]
Define a new label in the new category.
category = findCategory(mainProject,"Engineers"); createLabel(category,"Bob");
Get the label definition object for the new label.
ld = findLabel(category,"Bob")
ld = LabelDefinition with properties: Name: "Bob" CategoryName: "Engineers"
Attach a label to a project file. The label appears in the Labels column in the Project panel.
myfile = findFile(mainProject,"source/timestable.mlapp"); addLabel(myfile,"Engineers","Bob");
Get a particular label and attach text data to it.
label = findLabel(myfile,"Engineers","Bob"); label.Data = "Email: Bob.Smith@company.com"
label = Label with properties: File: "/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/source/timestable.mlapp" DataType: "char" Data: 'Email: Bob.Smith@company.com' Name: "Bob" CategoryName: "Engineers"
Retrieve the label data and store it in a variable.
mydata = label.Data
mydata = 'Email: Bob.Smith@company.com'
Create a new label category with data type double, the type MATLAB commonly uses for numeric data.
createCategory(mainProject,"Assessors","double"); category = findCategory(mainProject,"Assessors"); createLabel(category,"Sam");
Attach the new label to a specified file and assign data value 2 to the label.
myfile = mainProject.Files(10); addLabel(myfile,"Assessors","Sam",2)
ans = Label with properties: File: "/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/utilities/editTimesTable.m" DataType: "double" Data: 2 Name: "Sam" CategoryName: "Assessors"
Find all files with the label Sam
.
SamFiles= findFiles(mainProject,label="Sam")
SamFiles = "/tmp/Bdoc25a_2864802_1232970/tpeb93597e/matlab-ex45698718/TimesTableApp/utilities/editTimesTable.m"
Close Project
Close the project to run shutdown scripts and check for unsaved files.
close(mainProject)
To check for project shutdown issues, use the listShutdownIssues
function.
shutdownIssues = listShutdownIssues(mainProject)
shutdownIssues = 1×0 Issue array with properties: ID Details ProblemFiles ProjectRoot Exception