Today I want to talk about Referenced Projects. They can be very useful to componentize a large project, allowing for modular work, component reuse, unit testing, etc.
Working in technical support and interacting with users from all kinds of industries, I often see MATLAB Projects referencing 20, 50, or even 100 projects. Obviously, not all those are organized the same way.
In this post, I will describe the main types of setups I see. I would like to hear your thoughts in the comments below on your preferred way to organize referenced projects and why. I also created a poll that you should see on the left of this post.
To add a referenced project to your current project, start by clicking on the References button in the Project toolstrip:
This will open the Add Reference dialog and allow you to select the reference type. Let's start with one that I don't see being used very often: Absolute.
As the dialog says, you must ensure that the location is available to all users. This can be useful to include a utility project for which all users in the company need to use the same version, stored in a network location available to all users.
A more common way of organizing referenced projects is to specify their location relative to the top project. Among the projects we ship as examples and projects I receive from users, I typically see two types of relative setup:
Let's see the implications associated with those two architectures.
Relative - Outside
If you look at the example Work with Referenced Projects, you will notice that it references two projects. If you select either of the two, you will see that they are both in a relative location that begins with "../", meaning that they are stored in a folder beside the main project top folder:
With this setup, you will not see the files from the referenced projects in the "Files" view:
Instead, you can go to the References view and click the Show/Hide Files button on the top right to view the files for the selected referenced project:
This setup can be useful if multiple referenced projects are themselves referencing a common project. Placing all the projects side by side allows the common referenced project to be referenced using "../" by multiple projects. Here is a screenshot from the Powertrain Blockset example Conventional Vehicle Reference Application where the project VehicleConfig is referenced four times.
Relative - Inside
If your project is under Git source control and you would like to include a referenced project stored in a separate repository, you can do it using submodules. Begin by clicking on the Submodules icon on the toolstrip:
In the submodules window, click Add and you will see that the submodule path must be inside the main project:
Once the submodule has been added to the project, you can then add it as a referenced project using the same steps as described at the beginning of this post:
One thing I like when using a relative path inside the main project is that I can see all the files in the main project window, including the files in the referenced projects. As you can see, the Status and Git columns have icons indicating that those files are in referenced projects and submodules.
Another advantage of placing the projects you want to reference inside the main project folder is that we can identify if they have not been configured as referenced projects properly. For that, use the runChecks function or click on the Check Project button in the Tools gallery of the project window. (Tip: I made the Check Project button a favorite, so it shows up at the top of the gallery)
If we find projects in sub-folders inside your project that are not marked as referenced projects, we will let you know and offer to fix it in one click:
Now it's your turn
I would really like to hear your opinion on this type of project componentization choices. Are you on team "Outside" or team "Inside"? Or maybe you found the perfect combination of both?
Take a few seconds to respond to the poll on the left of this post and share your thoughts in the comments below.