Organize Large Modeling Projects Using Referenced Projects

MATLAB^® supports large-scale project componentization by allowing you to reference other projects from a parent project. Organizing large modeling 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.

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

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

When you open a project, referenced projects load first. This action adds the referenced project paths to the MATLAB search path and runs any startup actions that you specified in the referenced projects. To view all other projects that the current project references, in the Project toolstrip, in the Environment section, click References. The References tree shows all projects in the hierarchy.

This example project references two other projects. To download this example project hierarchy, see Open Example Project Hierarchy.

If the hierarchy has any missing projects or a project that introduces a circular dependency, an icon appears next to the project in the References 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.

Open Example Project Hierarchy

Open the example to download the supporting projects. This example opens the top-level Airframe project that has two referenced projects SignalMultiplier and WindGustLibrary.

The top-level Airframe example project provides an airframe simulation. To use additional functionalities available in Signal Multiplier and Wind Gust library, the top-level project adds them as referenced projects.

• The Signal Multiplier referenced project shows how to develop an S-function in a component independent from the top-level project. The referenced project provides source code, build support and path management. The build folder is on the project path. This ensures it is also on the top-level project path. The project has a Rebuild S-function shortcut.

• The Wind Gust Library referenced project provides a library and a data dictionary that contains the required bus objects for the library. This project path ensures that the library is set up for use in the top-level project.

Add or Remove Reference to Another 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 References.

2. In the References tab, click New Reference. 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 load sequence 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.

To view the information of a referenced project, in the References tree, select the project.

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

View, Edit, or Run Referenced Project Files

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, in the parent project, in the Project tab, click References. Then, in the References tree, select a referenced project.

• To modify or run a file, right-click the file and select from the list of available options.

• 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.

  

Extract a 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.

Consider the Airframe example project. Suppose you create a folder trial and carry out development work within the folder. You produce:

• Shortcuts to a Simulink^® library, a MATLAB file, and a Readme document

• Design and source code folders

• Data files

For easier management, you want to convert the trial folder into a separate component. In addition, you want access to the folder contents, for example, shortcuts to key files. To fulfill these requirements, extract the folder from the project and convert the folder into a referenced project.

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, such as a path to a network drive.

4. Click OK.

The folder trial and its contents are removed from the project. In the Shortcuts gallery, the trial section displays three new shortcuts.