| MATLAB® | |
| On this page… |
|---|
How MATLAB® Software Determines Which File to Run How MATLAB® Software Finds the Search Path, pathdef.m Viewing and Setting the Search Path |
The MATLAB® software uses a search path to find M-files and other files related to MATLAB, which are organized in directories on your file system. By default, the files supplied with MATLAB and MathWorks™ products are included in directories that are on the search path. This default search path includes many of the directories under matlabroot/toolbox, where matlabroot is the directory where MATLAB is installed, which you can determine by running the matlabroot function. By default, the top of the search path includes a user portion, userpath, whose default value varies by platform; for more information see the userpath reference page.
If you try to run or debug a file that is not in the current directory or not in a directory on the search path, the action fails. When this occurs in the Command Window, MATLAB errors. In the Editor/Debugger, a dialog box prompts you to
Change Directory — Makes the directory containing the file you want to run become the current directory
Add to Path — Adds the directory containing the file you want to run to the top of the search path
When there are two files with the same name, one in the current directory and the other in a directory on the search path, or both in directories on the search path, MATLAB follows rules to determine which to run—for more information, see How MATLAB® Software Determines Which File to Run.
The search path is also referred to as the path. Directories included are considered to be on the path. When you include a directory in the search path, you add it to the path. Subdirectories must be explicitly added to the path; a subdirectory is not on the path just because its parent directory is on the path. Adding directories to the path is similar to performing an include or import in some other applications.
For instructions to view the search path and add directories to it, see Viewing and Setting the Search Path, including Caution Against Saving Files in matlabroot/toolbox.
When there are two files with the same name, one in the current directory and the other in a directory on the search path, MATLAB runs the one in the current directory.
When there are two or more files with the same name, each located in a different directory on the search path, MATLAB runs the file located in the directory closest to the top of the search path, and MATLAB considers the other file to be shadowed. For this reason, the order of the directories on the search path is relevant.
In addition to files on the search path or in the current directory, other constructs in MATLAB might have the same name as an M-file. For example, if there is a variable named foo, and there is a function named foo is in a directory on the search path, when you type foo in the Command Window, MATLAB interprets foo as the variable rather than the M-file.
These situations are sometimes referred to as namespace conflicts or name clashes and can be the source of unexpected results or errors. There are other potential name conflicts such as with subfunctions and MEX-files—for more information, see Precedence Rules in MATLAB Programming Tips documentation.
Here are some guidelines for dealing with name clashes so that MATLAB runs the file you want it to run:
Change the current directory in MATLAB to the directory containing the file you want MATLAB to run.
To use a shadowed function, that is, a function with the same name as one that is located in a directory further up on the search path, move the directory containing the shadowed function to the top of the search path, or anywhere ahead of the other function with the same name. Alternatively, remove from the search path the directory containing the function you do not want to run.
For M-file scripts, you can use run with the full pathname for the M-file. For example, use run d:/mymfiles/foo.m to ensure that version of foo runs.
If you are not sure of the function MATLAB is using, run which for a specified function and MATLAB returns the full path to the function it is using.
The search path is stored in the file pathdef.m, which by default, is located in matlabroot/toolbox/local. You can store it in a different location, for example, the startup directory for MATLAB.
When MATLAB starts, it looks for a pathdef.m file in its startup directory. If none is found, it uses pathdef.m in matlabroot/toolbox/local. MATLAB modifies the path based on any path statements in a startup.m file. During a session, you can save changes to the path using the Set Path dialog box or the savepath function, and MATLAB uses the path you saved to for the remainder of the session.
If MATLAB finds a pathdef.m in the current directory, it uses that version. To avoid problems, do not maintain a pathdef.m file in a directory other than the startup directory for MATLAB or matlabroot/toolbox/local.
See also Saving Settings to the Path.
Use the Set Path dialog box to view and change the search path. For each feature of the Set Path dialog box, you can use functions as an alternative.
To access the dialog box, select File > Set Path, or type pathtool in the Command Window and press Enter. The Set Path dialog box opens.
Use the Set Path dialog box for the following actions. Equivalent functions are listed as well:
See also
The MATLAB search path field in the Set Path dialog box lists all of the directories on the search path. The top of the list is the start of the search path, while the bottom of the list is the end.
Any file you want to run or debug in MATLAB must reside in a directory that is on the search path, or in the current directory. If you create any files MATLAB processes, add the directories containing the files to the search path in MATLAB. You cannot add a file to the path, but rather you add the directory containing the file; all files in that directory are then on the search path.
By default, the top of the search path includes a user portion, whose default value, called the userpath, varies by platform. The userpath directory is automatically added to the search path upon startup. For more information, see the userpath reference page, and Changing the Startup Directory Via the userpath Function.
Function Alternative. Use the path function to view the search path.
Add directories to the search path when you want to run M-files in those directories.
To add directories to the search path using the Set Path dialog box,
Click Add Folder or Add with Subfolders.
If you want to add only the selected directory but do not want to add all of its subdirectories, click Add Folder.
If you want to add the selected directory and all of its subdirectories, click Add with Subfolders.
The Browse for Folder dialog box opens.
In the Browse for Folder dialog box, use the view of your file system to select the directory to add, and then click OK.
The selected directory, and subdirectories if specified in step 1, are added to the top of the search path.
To use the newly modified search path in future sessions, click Save. For more information about saving the path, see Saving Settings to the Path.
Click Close. If you did not save the changes in the previous step, the directories you added remain on the search path until you end the current session of MATLAB.
You cannot add method directories (directories that start with @) and private directories to the search path.
Adding Directories to the Path from the Current Directory Browser. In the Current Directory browser, select a directory, right-click, and select Add to Path from the context menu. Then select one of the submenus, for example, Selected Folder and Subfolders.
Function Alternative. To add directories to the top or the end of the search path, use addpath. The addpath function offers an option to get the path as a string and to concatenate multiple strings to form a new path.
You can include addpath statements in your startup M-file to automatically modify the path when MATLAB starts. For details, see Modifying the Path in a startup.m File.
The order of files on the search path is relevant — for more information, see How MATLAB® Software Determines Which File to Run.
To modify the order of directories within the search path,
Click one of the Move buttons, such as Move to Top. The order of the directories changes.
To use the newly modified search path in future sessions, click Save. For more information about saving the path, see Saving Settings to the Path.
Click Close. If you did not save the changes in the previous step, the new order of files on the search path remains in effect until you end the current session of MATLAB.
If you move the userpath directory from the top of the path to another position in the path and save the changes, upon the next startup, MATLAB automatically moves the userpath directory to the top of the path.
Function Alternative. While there is not a specific function to move directories, you can edit the pathdef.m file with any text editor to change the order of the directories. Use caution when editing the file so that you do not make MATLAB and toolbox functions unusable.
To remove directories from the search path using the Set Path dialog box,
To use the newly modified search path in future sessions, click Save. For more information about saving the path, see Saving Settings to the Path.
Click Close. If you did not save the changes in the previous step, the directories are removed from the search path until you end the current session in MATLAB.
If you remove the userpath directory from the search path and save the changes to the path, it also automatically clears the value for userpath, meaning that directory is no longer the startup directory.
Function Alternative. To remove directories from the search path, use rmpath.
You can include rmpath statements in your startup M-file to automatically modify the path when MATLAB starts. For details see Modifying the Path in a startup.m File.
To restore the default search path, click Default in the Set Path dialog box. This changes the search path so that it includes only the directories installed with MATLAB and related products.
To restore the default value for the user portion of the path, userpath, run userpath('reset').
To restore the previous path, click Revert in the Set Path dialog box. This cancels any unsaved changes you have made in the Set Path dialog box.
When you make changes to the search path, they remain in effect during the current session in MATLAB. To keep the changes in effect for subsequent sessions, you need to save them. To save changes using the Set Path dialog box, click Save.
If you want to automatically use this search path in future sessions, save the path to your startup directory, which saves pathdef.m to that location. You can save the changes to the default pathdef.m file, in matlabroot/toolbox/local if you have write permission for that directory but see the following caution. Alternatively, you can include addpath and rmpath statements in a startup.m file, which avoids some problems you might have with saving the path, for example, using the same path with both Microsoft® Windows® and The Open GroupUNIX® platforms. For more information, see Using the Path in Future Sessions.
Note When MATLAB starts up, it may provide in the Command Window a list of invalid directories. These directories were previously in pathdef.m but were subsequently deleted. The directories do not now appear on the search path listing in the Set Path dialog box. Click Save to overwrite the pathdef M-file, thereby eliminating future reporting of these nonexistent directories. |
Caution Against Saving Files in matlabroot/toolbox. Save any M-files you create and any M-files supplied with products from The MathWorks that you edit in a directory that is not in the matlabroot/toolbox directory tree. If you keep your files in matlabroot/toolbox directories, they can be overwritten when you install a new version of MATLAB. Also note that locations of files in the matlabroot/toolbox directory tree are loaded and cached in memory at the beginning of each session of MATLAB to improve performance. If you save files to matlabroot/toolbox directories using an external editor or add or remove in from these directories using file system operations, run rehash toolbox before you use the files in the current session. If you make changes to existing files in matlabroot/toolbox directories using an external editor, run clear functionname before you use the files in the current session. For more information, see rehash or Toolbox Path Caching in the MATLAB® Program.
Function Alternative. Use savepath to save the current path to pathdef.m. Locate pathdef.m in your startup directory for MATLAB to automatically use it in future sessions. Consider using savepath in your finish.m file. To modify the default path upon startup, include addpath and rmpath functions in your startup.m file. For more information, see Modifying the Path in a startup.m File.
There are three basic ways for MATLAB to automatically use a search path you specify, each with advantages and disadvantages:
For background information, see How MATLAB® Software Finds the Search Path, pathdef.m.
Put addpath and rmpath statements in a startup.m file, and include the startup file in the startup directory for MATLAB. When MATLAB starts, it uses the search path defined in pathdef.m in matlabroot/toolbox/local and modifies it based on the commands in the startup.m file.
By maintaining an unaltered pathdef.m in matlabroot/toolbox/local, you avoid inadvertently removing directories provided by The MathWorks from the path. This method continues working even when you update to a new version of MATLAB. If you run MATLAB on both Windows and UNIX platforms, this method works well — for example, for each platform, include separate addpath sections in the startup.m file, with each section preceded by an ispc or isunix statement.
One disadvantage of this method is that changes you make to the path using the Set Path dialog box are not incorporated in the startup.m file.
Copy pathdef.m from matlabroot/toolbox/local to the startup directory for MATLAB. Make changes to the path using the Set Path dialog box, and with addpath and rmpath functions — choose whichever suits your needs. You can use this method if you do not have write access to matlabroot/toolbox/local.
There are some disadvantages to this method. You might inadvertently remove directories supplied by The MathWorks from the path. When you update to a new version of MATLAB, you cannot use the pathdef.m file in the startup directory, but must delete it and create a new version. If you run MATLAB on both Windows and UNIX platforms, you need to maintain a separate pathdef.m file for each.
If you have write access to matlabroot/toolbox/local, make and save changes to the path using the Set Path dialog box, and with addpath and rmpath functions — choose whichever suits your needs.
There are some disadvantages to this method. You cannot maintain this file when you update to a new version of MATLAB, but will need to use the new default pathdef.m and make changes to it. If you run MATLAB on both Windows and UNIX platforms, you need to maintain a separate pathdef.m file for each.
If you get unexpected results that are related to the search path, you can try to correct the path file or restore the default path. You might experience path problems if you save the path on a Windows platform and then try to use the same pathdef.m file on a UNIX platform. Similarly, you might experience problems if you edit the pathdef.m file directly and make it invalid, or if the file becomes corrupt, renamed, or lost.
For example, if an error message similar to the following appears when you start MATLAB
Warning: MATLAB did not appear to successfully set the search path...
it indicates a problem with the search path and you will not be able to use MATLAB successfully.
To recover from problems with the search path, try the following, in order, proceeding to the next step only if needed:
View the pathdef.m and startup.m files, looking for obvious problems. Make changes and save them. If path problems appear to be resolved, start MATLAB again to be sure the problem does not reappear. Depending on the problem, you might not be able to even view the pathdef.m file.
Use the default path for products from The MathWorks. In the Set Path dialog box, select Default, then Save, then Close. Depending on the problem, you might not be able to even open the dialog box.
Run restoredefaultpath. This sets the search path to include only installed products from The MathWorks. If that seems to have corrected the problem, run savepath. Start MATLAB again to be sure the problem does not reappear.
Depending on the problem, this might generate a message such as
The path may be bad. Please save your work (if desired), and quit.
If so, perform step 4.
Perform these steps after trying step 3.
Run
restoredefaultpath; matlabrc
This might run for a few minutes. It sets the search path to include only installed products from The MathWorks and corrects path problems encountered during startup.
If there is a pathdef.m in your startup directory for MATLAB, it caused the problem. So either remove the bad pathdef.m file or replace the with a good pathdef.m file, for example, one you can generate at this point with
savepath('path_to_your_startup_directory/pathdef.m')Start MATLAB again to be sure the problem does not reappear.
| Viewing and Editing Workspace Variables with the Variable Editor | File Management Operations | |
| © 1984-2008- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |