MATLAB(TM) Hypertext Reference, Copyright (c) 1995--2004 Gerald Recktenwald, All rights reserved

Setting the Internal MATLAB Path

Update of April 2004:

With MATLAB version 6.x and later, a good solution for setting the path is to use the Path Browser. Type help path or helpwin('path') at the command prompt for more information. The rest of this web page still applies (more or less) because the Path Browser merely automates the construction of the pathdef.m file.

For students in the College of Engineering and Computer Science, I have a recommended procedure for setting up a shortcut to the MATLAB program on the file server. The procedure applies to Windows 2000/XP computers when the MATLAB executable is installed on a Windows file server. Although the details are specific to our local network, the only changes that need to be made for other locales is in the specification of the directory for the MATLAB binary. In other words, adapting this procedure for another network primarily involves changing where your system administrator has stored the MATLAB program.

Background Information

The MATLAB program consists of relatively small executable (a kernel) and a library of many, many functions stored on the hard disk of your computer. Once MATLAB is properly installed it knows where to find its own libraries. There are many situations, however, where you require MATLAB to interact with your files. How does MATLAB know where your files are?

MATLAB stores a list of directories in an internal variable called the path. This is just like the system path variable in Unix, DOS, and Windows computers, except that it is an internal MATLAB variable: MATLAB does not use the system path for its internal path. When you ask MATLAB to use one of its library functions, or to read data from one of your files, MATLAB looks for that function or that file only in the directories in its internal path.

n.b. If you consider yourself a computer stud or studette you may want to skip to the ultimate path solution right now.

Suppose your friend, John, tells about you his wonderful new MATLAB function (a.k.a. m-file) called ``boingo''. John says that to use it you just type boingo at the MATLAB prompt. You follow his directions, but instead of something wonderful this is how MATLAB replies.

	>> boingo
	??? Undefined function or variable boingo.
This response can drive you utterly batty, especially if right there, in the directory in front of you (in another window) you see the file ``boingo.m''. The problem here is that although you can see the file, MATLAB cannot. MATLAB only knows about the files in its internal path, and boingo.m is not in it.

There are several ways to set MATLAB's internal path variable so that it can find boingo.m.

The manual 'cd' approach

I prefer the manual 'cd' approach when I want to do a quick, one-of-a-kind calculation.

MATLAB always has a current working directly (current working folder). To see the contents of this directory type ``what'' or ``dir'' at the MATLAB prompt. When you launch MATLAB the current working directory depends on the type of computer you are using.

The manual 'cd' approach involves using the steps native to your operating system to change the current directory (cd) from within MATLAB. The goal is to change from the current working directory at the MATLAB launch, to the directory containing your files. On Macs and Windows computers this means using the ``Open'' command in the ``File'' menu. I use the open file dialog box to switch directories and then when ``boingo.m'' is in sight I hit the ``Cancel'' button.

On a DOS or Unix computers you can use the ``cd'' command from within MATLAB to change directories to the one containing ``boingo.m''. Actually, my prefered technique for these computers is to ``cd'' into the directory containing boingo.m before I launch MATLAB. Again, this works best for quick, one-of-a-kind calculations. Read on for more robust solutions.

The manual approach using the path command

Once again the exact steps depend on the type of computer you are using. Here the only difference is the character used to separate the directories in the path specification. Suppose that ``boingo.m'' is in the ``John'' directory, which is in the ``home'' directory, which is in the ``user'' directory of the hard disk. In other words the full path to boingo.m on a Unix computer is
where /user is a directory below the root.

On a DOS or Windows computer the full path is

where the user directory is assumed to be on the c: drive.

On a Macintosh the full path is

where ``user'' corresponds to the name of the hard disk on your Mac.

To set the path to include boingo.m type the following MATLAB commands

	>> P=path;
	>> path(P,'/user/home/John')
substituting (as necessary) the path description appropriate to your computer. The first statement assigns the current path to the variable named ``P''. The second statement appends the path /user/home/John to the current path.

Note that you should use this approach to append a path to the internal MATLAB path. If you replace the path with path('/user/home/John') then MATLAB will roll over and die when you type in the next command.

The semi-automatic 'setPathScript' approach

This approach involves automating the steps used in the preceding mScripts for more information). This approach is very useful if you frequently use a the same set (or sets) of files in your MATLAB work. I consider a combination of a path-setting script with the MATLABPATH approach, described below, to be the ultimate solution to your path problems.

Create a two-line script file containing the statements described in the preceding section. For the ``boingo.m'' example we've been working with I would call the script JohnPath.m. Where you store this script depends on the kind of computer you are using.

Stand-Alone Personal Computers
Save the script file in the directory (or a subdirectory) in which the MATLAB application is stored. MATLAB automatically includes these directories in its path. As a matter of style I create a ``Gerry/local'' directory for storage of this and other handy scripts. The directory title tells me that these files are not part of the standard MATLAB distribution -- a handy piece of information when it's time to update/upgrade.

Unix Computers and File Servers
Save the script file in the MATLAB/local subdirectory of your login directory. (You probably do not have write priveledges for the directory containing the MATLAB binaries so you can't rely on the default path technique accessible to users of stand alone personal computers.) You will also need to set the MATLABPATH environment variable.
If you've gotten to this point in the page and you can't understand what's going on -- if for example you consider yourself a computer stud or studette -- then you'll just have to read backwards far enough to you figure out how to use the ultimate path setting technique. This shouldn't be hard for a stud. :^)

The fully-automatic MATLABPATH approach

MATLABPATH is an environment variable that MATLAB reads at startup. Any paths in the MATLABPATH variable are appended to MATLAB's internal search paths. The particulars of working with environment variables vary with the operating system. Below I give you my advice on setting up the MATLABPATH variable. The ultimate reference, of course, is the MATLAB User's Guide for your computer.

Unix Systems
On a Unix computer you can set the MATLABPATH environment variable by typing something like the following at the sytem prompt (not the MATLAB prompt)
   setenv MATLABPATH /u/gerry/MATLAB/local:/u/gerry/MATLAB/CVFD
MATLAB reads the MATLABPATH environment variable on startup, so the preceding is equivalent to adding two directories
to the internal MATLAB path. Note the colon separating the two paths in the setenv command. Rather than type this command each time I want to use MATLAB, I include it in my .cshrc file.

The MATLABPATH variable could include references to all of your directories containing MATLAB code. I prefer, however, to keep this environment string shorter. In the preceding example the first directory I add to my MATLAB path is /u/gerry/MATLAB/local. This is where I stash a number of short little scripts to do various things, including setting the path. For example, you could write a number of two line scripts that set a paths similar to the JohnPath.m file shown in the example above.

There are no environment variables in the Macintosh OS. Instead the Mac version of MATLAB allows you to make a semi-permanent change to its configuration with the ``Set Path...'' command in the ``File'' menu. Refer to the User's Manual for more information. I do not use this approach. Instead I follow the procedure described for stand-alone personal computers, above. In other words I store my path-setting scripts (and other goodies) in a ``Gerry local'' folder inside the folder that contains the MATLAB application. Note that MATLAB does not resolve aliases in building its internal path.

Windows 2000/XP
Have a look at the recommended procedure for students in the Mechanical Engineering Department. For a stand-alone installation (i.e. a student version of MATLAB on your personal computer) substitute the MATLAB installation directory for the P:... specification.

[Master Outline]