Componentize Large Projects

R2026b

MATLAB^® supports large-scale project componentization by allowing you to reference other projects or packages from a parent project. Organizing large projects into components facilitates code reuse, modular and team-based development, unit testing, and independent release of components.

When you organize a project into smaller projects through project referencing, from a parent project, you can:

• Access the project paths, shortcuts, and source control information for all referenced projects.

• View, edit, and run files that belong to referenced projects.

• Move files between projects in the same project hierarchy.

  Renaming, moving, or removing a file in the project hierarchy triggers an analysis and prompts you to update the file usages in the project itself and in all upstream projects in the hierarchy. (since R2025a)

• Run a dependency analysis on the current project and all its referenced projects. For more information, see Analyze Project Dependencies.

If your project uses the one-file-metadata TOML format as the definition file type, you can also reference packages from the parent project. For more information about packages, see Release and Manage Package Dependencies and Versioning Using Projects. (since R2026b)

View Project Dependencies

When you open a project, to view all the other projects that the current project references, in the Project toolstrip, in the Environment section, click Dependencies. The Dependencies tree shows all the specified dependencies in a hierarchical tree format.

Before R2026b: To view all the other projects that the current project references, in the Project toolstrip, in the Environment section, click References.

This example project references four other projects.

For a top-level project that contains both package and project dependencies, the tree view features four columns:

• Dependency — Name of the dependency

• Installed Version — Installed version for each package dependency

• Required Version — Required version for each package dependency

• Location — Project path for each project dependency

You can also display the top-level project dependencies using a list. (since R2026b) To show a list of dependencies, in the Project toolstrip, in the Environment section, click Dependencies. Then, in the View section, click List View. The Dependencies list shows the projects and packages in a flat format across two tables. This list allows you to quickly identify the number of dependencies and which projects or packages are included in the top-level project hierarchy.

For project dependencies, the list view features the name and the path of each referenced projects. For package dependencies, the list view features the resolved and the latest compatible version.

Alternatively, you can view the referenced projects and packages of a top-level project programmatically by using the ProjectDependencies property of the matlab.project.Project object.

proj = currentProject;
proj.ProjectDependencies

1×4 Dependency array with properties:

    Name
    VersionRange
    ID
    Path
    Absolute
    ResolvedVersion
    ResolvedPath

proj.ProjectDependencies.Name

ans = 
    "AudioEnhancement"

ans = 
    "ExternalLibrary"

ans = 
    "ImageProcessing"

ans = 
    "MachineLearningModels"

If the hierarchy has any missing projects or a project that introduces a circular dependency, an icon appears next to the project in the Dependencies tree. You can also see the same information listed in the Startup tab in the Project Issues panel. For more information about project startup and shutdown issues, see Run Project Checks.

Add or Remove Reference to a Project

You can add new components to a project by referencing other projects.

To add a reference to a project, follow these steps.

1. On the Project tab, in the Environment section, click Dependencies.

2. In the Dependencies tab, click New Dependency. Then, select one of the available options.

   • If the project you want to reference has a well-defined root folder relative to the parent project root folder, select Relative.

   • If the project you want to reference is in a shared location accessible to your computer, for example, on a network drive, select Absolute.

3. Browse to select the required project using the PRJ file.

4. Click Open.

When the referenced project loads, MATLAB adds the referenced project path to the MATLAB search path and then runs or loads specified startup files. Similarly, when the referenced project closes, MATLAB removes the project path from the search path and runs specified shutdown files. MATLAB loads referenced projects before their parent projects. This allows the parent project to access the referenced project in startup and shutdown files.

Tip

You can also populate a referenced project by cloning a project under Git™ source control as a submodule. After cloning the project submodule, add it as a referenced project using the same steps. For more information, see Organize Projects into Components Using References and Git Submodules (Simulink).

To remove a project reference from your project hierarchy, in the Dependencies tree, select the referenced project. Then in the Dependencies tab, in the Selection section, click Remove.

Extract Folder to Create a Referenced Project

You can extract an existing folder in a project to create a referenced project. After extracting a folder, file and folder contents and shortcuts in the referenced project remain accessible from the parent project.

To extract a folder from a project and convert the folder into a referenced project, follow these steps.

1. In the Project panel, right-click the folder and select Extract to Reference Project.

2. In the Create Reference Project dialog box, specify a project name and location.

3. In the Reference type section, select either Relative or Absolute. Select Relative if you specify the new project location with reference to the current project root. Select Absolute if you specify the full path for the new location, which is, for example, on a network drive.

4. Click OK.

The software removes the selected folder and its contents from the project and creates a new referenced project.

If the folder contains any files associated to shortcuts in the parent project, the shortcuts move to the referenced project and are accessible from the Shortcuts gallery. If any of the files in the folder have labels, the used labels move to the referenced project as well.

View, Edit, and Run Referenced Project Files and Shortcuts

If you have a project that references other projects, you can view, modify, or run the files that belong to the referenced projects directly from the parent project.

To view a referenced project and all its content, open the parent project. Then, in the Project panel, next to the View option, select a referenced project. The Project panel now shows all the files and folders inside the selected project. (since R2026b)

Alternatively, in the parent project, in the Project tab, click Dependencies. Then, in the Dependencies tree, select a referenced project.

• To view the files inside the referenced project, right-click the referenced project in the Dependencies tree and select Show Files. Alternatively, in the Dependencies tab, in the Selection section, click Show Files. Both these actions show the selected referenced projects files in the Project panel.

• To open a referenced project as a top-level project, right-click the referenced project in the Dependencies tree and select Open Project.

If the referenced project is under source control, to view the source control details, right-click in the white space and select Source Control > View Details.

To access shortcuts of the projects referenced by the open project, in the Project toolstrip, expand the Shortcuts gallery. If you cannot see the referenced projects shortcuts, select the Show project references check box. For information on how to create and edit shortcuts, see Create Shortcuts to Frequent Tasks.

You can also programmatically edit referenced projects without opening them as top-level projects.

1. Open the top-level project.

   mainProj = openProject("MyTopLevelProject");

2. Create a project object for the referenced project.

   refProj=mainProject.ProjectReferences.Project;

3. Edit the referenced project without loading it as a top-level project. For example, add a new file to the referenced project.

   addFile(refProj,"newFile.m");

(since R2026a)