Main Content

Componentize Large Projects

MATLAB® supports large-scale project componentization by allowing you to reference other projects from a parent project. Organizing large projects into components facilitates code reuse, modular and team-based development, unit testing, and independent release of components. For more information, watch How to Organize Large Projects into Components (3 min, 32 sec).

Projects can reference multiple other projects in a hierarchical manner. The project reference hierarchy appears as a tree in the References view.

From a parent project, you can

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

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

  • Detect changes in referenced projects using checkpoints.

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:

  1. On the Project tab, in the Environment section, click References. The Add Reference dialog box opens.

  2. Browse to select the required project (.prj) file.

  3. In the Reference type field, select either Relative or Absolute. Select Relative if your project hierarchy has a well-defined root relative to your project root. For example, your project root might be a folder under source control. Select Absolute if the project you want to reference is in a location accessible to your computer, for example, a network drive.

  4. To create a checkpoint when you add the project, select Set a checkpoint to detect future changes. For more information about checkpoints, see Manage Changes in Referenced Project Using Checkpoints.

  5. Click Add.

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.

To remove a referenced project from your project hierarchy, in the References tree, right-click the referenced project and select Remove Reference.

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, select the References view. In the References tree, select a referenced project.

To display the referenced project files, at the top right of the References view, click Show Files.

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

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:

  1. In the Files view, right-click the folder and select Extract to Referenced Project. The Extract Folder to New Project dialog box opens.

  2. Specify a project name and location

  3. In the Reference type field, 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. To disable any of the default content migration actions, click More Options and clear the corresponding check boxes.

  5. Click Extract.

  6. In the two Warning dialog boxes that open, click OK.

The selected folder and its contents are removed from the project. On the Project Shortcuts tab, the Referenced Projects section shows a new shortcut for the referenced project.

Manage Changes in Referenced Project Using Checkpoints

To detect and compare changes in a referenced project, create checkpoints. You then can compare the referenced project against the checkpoint to detect changes.

By default, MATLAB creates a checkpoint when you add a reference to a project. To create additional checkpoints:

  1. In the parent of the referenced project, select the References view.

  2. To create a checkpoint, go to the References tab, and in the Checkpoint section, click Update. In the Details view, the Checkpoint field displays the timestamp of the latest check point.

To detect changes in a referenced project, go to the References tab, and in the Checkpoint section, click Checkpoint Report. The Difference to Checkpoint dialog box displays the files that have changed on disk since you created the checkpoint.

To remove the checkpoint, in the Checkpoint section of the References tab, click Clear.

Related Topics