IN THIS CHAPTER
Defining the project and seeing how to use it
Creating a project structure
Performing checks on your project setup
The term project gets used in all sorts of places. In fact, most people have a to-do list right there on their desk that’s packed with projects they may never accomplish. People think about them, though and then push them further down on the list as new projects (that also won’t get done) take their place. A MATLAB project is documentation for a task that you contemplate, devise, or plan. Your MATLAB project, as described in the early part of this chapter, is a specific kind of documentation for tasks that you perform in MATLAB so that you can obtain repeatable results.
Projects have a specific format. You use a particular way of describing how to do something so that anyone who views the project also understands the process used to accomplish the task. The next part of the chapter helps you understand the project structure. When creating a MATLAB project, you can choose a blank project or one created from a source, such as a folder, Git, or Subversion (SVN). You also create projects as part of packaging an app (as described in the “Packaging Your App” section of Chapter 14).
Because a project is a kind of process, you must also ensure that your project will produce the desired result. Checking your project for flaws will reduce the risk of someone producing apps or performing other MATLAB tasks inconsistently. The last section of the chapter helps you create consistent and useful projects.
You don’t have to type the source code for this chapter manually. In fact, using the downloadable source is a lot easier. You can find the source for this chapter in the \MATLAB2\Chapter15 folder of the downloadable source. When using the downloadable source, you may not be able to work through some of the hands-on examples because the example files will already exist on your system. In this case, you can create an alternative folder, Chapter15a, to hold the results of the hands on exercises. See the Introduction for details on how to obtain the downloadable source.
Considering the Need for Projects
If you work by yourself or in a small group on a limited research task, you likely don’t need a project. However, research and other MATLAB-related tasks tend to grow and become a lot larger than anticipated. You might have hundreds of people all working together toward a common goal; the task itself might span years; or the task could become so complicated that you need organizational aids to understand it. With these sorts of issues in mind, you may need help with
· Automating startup and shutdown tasks
· Devising easy access to frequently performed tasks
· Creating projects based on current conditions
· Managing projects based on environmental changes
· Reducing the complexity of large projects
· Sharing projects with others
· Upgrading or updating an existing project
· Considering project dependencies
· Developing a method of performing tasks that aren’t performed often enough to memorize the process, but are performed often enough to pay back the time for developing the project
· Using source control to manage the project
The overriding goal of a project is to think about what you want to accomplish and how to accomplish it. Although some people just plunge in and start working toward a goal, using this approach is often error prone and counterproductive because you waste a lot of time pursuing false leads. Using projects is an organized method of interacting with MATLAB on a large scale.
Creating a New Project
Before you can use a project to manage anything, you must create one. MATLAB provides a number of methods to create projects, as described in the following sections. The example relies on creating a blank project so that you can see how the various features work without becoming involved in third-party aspects, such as source control.
You need to perform additional setups to use MATLAB with a source-control manager. The two integrated support mechanisms are Git (see https://www.mathworks.com/help/matlab/matlab_prog/set-up-git-source-control.html for setup requirements) and SVN (see https://www.mathworks.com/help/matlab/matlab_prog/set-up-svn-source-control.html). It’s theoretically possible to use other source-control managers, but you must perform a lot of manual configuration to get the job done. The articles at https://www.mathworks.com/help/matlab/matlab_prog/about-mathworks-source-control-integration.html and https://www.mathworks.com/help/matlab/matlab_prog/customize-external-source-control-to-use-matlab-for-comparison-and-merge.html provide a starting point for this task.
Choosing a project type
You need to choose a project type as a first step to creating a project. MATLAB provides menu options to create the following four project types:
· Blank Project: You start the project from scratch.
· From Folder: The project begins with the files found in a specific folder of your choosing. Using this project type saves time when you already have the files you want to use for the project in one place.
· From Git: The project begins with the files found in a Git repository. MATLAB also performs some configuration steps required to use Git as a repository and source-code manager.
· From SVN: The project begins with the files found in a SVN repository. MATLAB also performs some configuration steps required to use SVN as a repository and source code manager.
This example uses a blank project to enable you to see the various steps involved. The following steps help you create the project:
1. Choose New ⇒ Project ⇒ Blank Project in the File section of the Home tab.
You see a New Project dialog box, like the one shown in Figure 15-1. This dialog box has example entries already configured in it.
FIGURE 15-1: Provide a name and location for your project files.
2. Type a name in the Project Name field and select a location in the Project Folder field; then click Create.
You see a Welcome to Your Project dialog box like the one shown in Figure 15-2. To create a project, you perform all three tasks: adding files, setting paths, and determining whether to run your project at startup, before you move on. You can click Learn More to see help files for each of the tasks, or click Skip if you want to get started configuring your project immediately.
FIGURE 15-2: Review the welcome screen items before moving on if necessary.
3. Click Skip.
You see the Project editor display, shown in Figure 15-3. This is where you start defining how your project is put together.
You need some files to use to work with your project. Rather than start completely from scratch, copy Factorial1.m from the Chapter10 folder and paste it into the Chapter15 folder. Open the file and remove the fprintf() and disp() lines so that you don’t see the interim steps. Now create a new script file using the techniques found in Chapter 8, name it TestFactorial1.m, and add the following code to it:
for testValue = 1:5
Output = Factorial1(testValue);
fprintf('%d! equals %d\n', testValue, Output);
FIGURE 15-3: The Project editor helps you configure your project.
If you run TestFactorial1.m at this point, you see the following output:
1! equals 1
2! equals 2
3! equals 6
4! equals 24
5! equals 120
Using the Project editor
The Project editor (refer to Figure 15-3), enables you to configure your project. (The Project editor was formerly called the Project Live editor.) One of the odd parts of this process is that you must tell Project editor where to find your files before adding files to the project (even if these files are in the current directory). That’s why the following sections have you setting the project path first, before you add files.
Your project must have at least one path to work correctly. To add a path, click Project Path in the Environment section of the Project tab. You see the Manage Project Path dialog box, shown in Figure 15-4.
Click Add with Subfolders because the Chapter15 folder contains a resources subfolder, which MATLAB automatically creates as part of creating the project. You see an Open dialog box, where you can highlight the Chapter 15 folder and click Select Folder. You see a new [project root] entry in the list of folder, which is all you need. Click Close to close the Manage Project Path dialog box.
FIGURE 15-4: Set the path information for your project.
Adding files to your project is easy. Just drag the file from the Current Folder pane and drop it in the right pane of your project. This project contains two files: Factorial1.m and TestFactorial1.m. Because TestFactorial1.m depends on Factorial1.m, add Factorial1.m first, and then drag TestFactorial1.m into the project.
Notice the Classification column of the project. This column tells you the purpose of a particular file. The default classification is Design because MATLAB assumes that you use it most often. However, TestFactorial1.m isn’t a design file; it’s a test file. Select TestFactorial1.m. Drag Classification\Test from the Labels pane and drop it on TestFactorial1. The display changes, as shown in Figure 15-5. You can now sort your files by classification when needed.
FIGURE 15-5: Add files and define their classification.
Note that you can drag and drop files from other folders. For example, try opening the Chapter10 folder and dragging Factorial2.m to the right pane of the project. You see Factorial2.m added to the list and to the Current Folder pane. If you want to test Factorial2.m, you can add this code to TestFactorial1.m:
for testValue = 1:5
Output = Factorial2(testValue);
fprintf('%d! equals %d\n', testValue, Output);
Determining when to run your project
You use the startup and shutdown settings to ensure that your project works as anticipated. The startup files will typically perform any required configuration, so you don’t have to depend on the project user doing it. The shutdown files will perform any required cleanup so that you don’t end up with bits and pieces of old material hanging around. To configure your project to provide startup and shutdown support, click Startup Shutdown in the Environment section of the Project tab to display the Manage Project Startup and Shutdown dialog box, shown in Figure 15-6.
FIGURE 15-6: Select files to run to perform startup and shutdown tasks.
To add a script or Live Script file to either list, click Add. You wouldn’t use other file types here because the file needs to execute by itself. When you decide that you no longer need to perform a startup or shutdown task, select the associated file in the list and click Remove.
Adding project details
At some point, you want to describe your project so that other people know what it does. To do this, click Details in the Environment section of the Project tab. You see the Project Details dialog box, shown in Figure 15-7.
FIGURE 15-7: Describe your project so that others know what it does.
You do want to provide a new entry in the Name field, such as My First Project. A good description will help others know what your project does and why you created it. If your project requires special resources or has unique usage instructions, you might want to include them here as well.
Normally, you don’t need to change the Project Root field unless you change the location of the resource files used with the project. Likewise, you normally leave the Current Folder entry alone. After you finish describing your project, click OK to save the settings and clear the Project Details dialog box.
Referencing other projects
Projects can (and should) be modular. You can create a project that does just one thing well, and use it as a standalone project. However, you might also want to use that project with other projects. Perhaps a master project calls on features of a subordinate project. In this case, you add a project reference, which is a pointer to another project that you use for some other purpose. To add a project reference, click References in the Environment section of the Project tab to display the Add Reference dialog box, shown in Figure 15-8.
PROGRAMMATICALLY CREATING PROJECTS
The easiest way to work with projects is to use the MATLAB GUI, as this chapter does. However, you might need to work with projects programmatically as part of a script or function. In this case, you can use the functions listed at https://www.mathworks.com/help/matlab/projects.html, which divide project management into these topics:
· Creating and exporting projects
· Setting projects up
· Managing project files
· Working with project objects
FIGURE 15-8: Add references to other projects as needed.
This dialog box lets you create references to other projects, not other resources. If possible, use a relative reference to create flexible references to the other projects. Using absolute makes the reference brittle because now you’re depending on a specific hard-drive location. You should also keep the checkpoint intact so that MATLAB automatically looks for future changes for you.
Understanding the Project Dependencies
A project dependency defines a relationship between two resources. For example, you can’t run TestFactorial1.m by itself—you must have Factorial1.m as well. However, it’s not a two-way dependency. You can run Factorial1.m by itself without any problem. (If you added Factorial2.m in the “Adding files” section, the same dependency results, but there is no dependency between Factorial1.m and Factorial2.m.) The point is that you don’t want to send this project to anyone without all the required files, which can become a difficult proposition because of any of these actions:
· The project had files added to it by several people.
· Files are removed as the project changes, only to be added back later.
· The version of a file changes, as indicated by its filename.
· Some files are located in other folders.
Fortunately, MATLAB provides the means for performing automatic dependency checks. Click Dependency Analyzer in the Tools section of the Project tab to see the Dependency Analyzer window, shown in Figure 15-9. This particular display shows the effects of various changes throughout this chapter, such as adding Factorial2.m and modifying the project name (see the “Adding project details” section, earlier in this chapter, for more information).
FIGURE 15-9: The Dependency Analyzer shows which files are dependent on others.
If you find that your output looks incorrect, choose Analyze ⇒ Reanalyze All in the Analyze section of the Analyzer tab. The Dependency Analyzer will require some time to recheck all the dependencies, so be patient.
Clicking various elements provides you with details in the Properties pane. For example, clicking TestFactorial1.m will show you its location and the type of file it is, in addition to showing you the files it requires. You can also click the various arrows. For example, the arrow showing that Factorial1.m calls itself tells you that this script is recursive.
Running Required Checks
You may want to verify the status of your project before you send it to anyone. MATLAB provides two checks that you can perform to ensure that your project will work, as described in the following sections.
Checking project integrity
A project integrity check ensures that the project will run. It looks for issues like missing files or paths that are incorrectly set. To use this check, choose Run Checks ⇒ Check Project in the Tools section of the MATLAB Project tab. You see a Project Integrity Checks dialog box, like the one shown in Figure 15-10, as output.
FIGURE 15-10: Locate any potential project integrity issues before sending it out.
In this case, the project passes with flying colors. However, if there were issues with the project, such as dependency files being outdated, MATLAB would provide you with details on what went wrong.
Looking for potential updates
If you want your project to run on other systems, it has to be compatible with those other systems. The best way to achieve this goal is to verify that all files use current calls and that the underlying files are up to date. The following steps help you verify that your project is current in every possible way to reduce the risk of compatibility issues with other systems.
1. Choose Run Checks ⇒ Upgrade Project in the Tools section of the Project tab.
You see the Upgrade Project dialog box, shown in Figure 15-11. This dialog box tells you how many files MATLAB will check and what checks it will perform. The default is to check everything.
FIGURE 15-11: Define the parameters of the checks you want to perform.
Clicking the Change Options link displays the Upgrade Options dialog box, which allows you to control which files are checked and the kind of checks performed on them. However, you normally want to check the entire project; otherwise, you can’t be sure that you won’t encounter compatibility issues. The only advantage to not checking everything is that the check takes less time. You could use this option if you know that only certain files are changed and you want to be sure that they’re up to date.
2. Click Upgrade.
You may need to wait a few seconds before seeing the Upgrade Project Report dialog box, shown in Figure 15-12. This dialog gives you an overall report on the project as a whole and then lets you drill down into individual files to look for potential errors. The output provides three different results:
· Passed: Nothing is wrong with the current check. However, this entry may include future issue warnings. For example, Figure 15-12 shows that Factorial1.m uses some calls that MATLAB will remove in the future. Highlight the entry and click the Learn More link to discover whether a fix for the issue exists.
· Passed with Fixes: There was a problem with the current check, but MATLAB was able to provide an automatic fix for you. The problem with this approach is that you can’t always be certain that MATLAB fixed the problem in the same manner as you would, so you need to verify the fix.
FIGURE 15-12: Generate a report telling you whether the project is up to date.
· Need Attention: You must manually fix the problem found by MATLAB. In this case, you click the file link shown in the display, such as $\Factorial1.m in Figure 15-12, to open the file in the editor and perform the correction. (Note that you may need to close the Upgrade Project Report dialog to use the editor.)
3. Select a file to fix; then click its link in the display.
MATLAB opens the file for you in the editor or Live Editor.
4. Perform any needed fixes or check any automatic updates; then click Rerun Checks in the Upgrade Project Report dialog, or click Run Checks ⇒ Upgrade Project in the Tools section of the MATLAB Project tab.
MATLAB performs the required checks on the selected file. If the changes you make are successful, the file will pass and you can move on to the next file in the list.
5. Perform Steps 3 and 4 for each file in the project until your overall score is 100% Passed.
6. Click Close.
The Upgrade Project Report will verify that you want to close the dialog box before closing.