11.10.1 Manipulating the Load Path

When a function is called, Octave searches a list of directories for a file that contains the function declaration. This list of directories is known as the load path. By default the load path contains a list of directories distributed with Octave plus the current working directory. To see your current load path call the path function without any input or output arguments.

It is possible to add or remove directories to or from the load path using addpath and rmpath. As an example, the following code adds ‘~/Octave’ to the load path.

addpath ("~/Octave")

After this the directory ‘~/Octave’ will be searched for functions.

: addpath (dir1, …)

: addpath (dir1, …, option)

Add named directories to the function search path.

If option is "-begin" or 0 (the default), prepend the directory name(s) to the current path. If option is "-end" or 1, append the directory name(s) to the current path. Directories added to the path must exist.

In addition to accepting individual directory arguments, lists of directory names separated by pathsep are also accepted. For example:

addpath ("dir1:/dir2:~/dir3")

The newly added paths appear in the load path in the same order that they appear in the arguments of addpath. When extending the load path to the front, the last path in the list of arguments is added first. When extending the load path to the end, the first path in the list of arguments is added first.

For each directory that is added, and that was not already in the path, addpath checks for the existence of a file named PKG_ADD (note lack of .m extension) and runs it if it exists.

See also: path, rmpath, genpath, pathdef, savepath, pathsep.

: genpath (dir)

: genpath (dir, skip, …)

Return a path constructed from dir and all its subdirectories.

The path does not include package directories (beginning with ‘+’), old-style class directories (beginning with ‘@’), private directories, or any subdirectories of these types.

If additional string parameters are given, the resulting path will exclude directories with those names.

See also: path, addpath.

: rmpath (dir1, …)

Remove dir1, … from the current function search path.

In addition to accepting individual directory arguments, lists of directory names separated by pathsep are also accepted. For example:

rmpath ("dir1:/dir2:~/dir3")

For each directory that is removed, rmpath checks for the existence of a file named PKG_DEL (note lack of .m extension) and runs it if it exists.

See also: path, addpath, genpath, pathdef, savepath, pathsep.

: savepath ()

: savepath (file)

: status = savepath (…)

Save the unique portion of the current function search path that is not set during Octave’s initialization process to file.

If file is omitted, Octave looks in the current directory for a project-specific .octaverc file in which to save the path information. If no such file is present then the user’s configuration file ~/.octaverc is used.

If successful, savepath returns 0.

The savepath function makes it simple to customize a user’s configuration file to restore the working paths necessary for a particular instance of Octave. Assuming no filename is specified, Octave will automatically restore the saved directory paths from the appropriate .octaverc file when starting up. If a filename has been specified then the paths may be restored manually by calling source file.

See also: path, addpath, rmpath, genpath, pathdef.

: path ()

: str = path ()

: str = path (path1, …)

Modify or display Octave’s load path.

If nargin and nargout are zero, display the elements of Octave’s load path in an easy to read format.

If nargin is zero and nargout is greater than zero, return the current load path.

If nargin is greater than zero, concatenate the arguments, separating them with pathsep. Set the internal search path to the result and return it.

No checks are made for duplicate elements.

See also: addpath, rmpath, genpath, pathdef, savepath, pathsep.

: val = pathdef ()

Return the default path for Octave.

The path information is extracted from one of four sources. The possible sources, in order of preference, are:

1. .octaverc
2. ~/.octaverc
3. <OCTAVE_HOME>/…/<version>/m/startup/octaverc
4. Octave’s path prior to changes by any octaverc file.

See also: path, addpath, rmpath, genpath, savepath.

: val = pathsep ()

Query the character used to separate directories in a path.

See also: filesep.

: rehash ()

Reinitialize Octave’s load path directory cache.

: fname = file_in_loadpath (file)

: fname = file_in_loadpath (file, "all")

Return the absolute name of file if it can be found in the list of directories specified by path.

If no file is found, return an empty character string.

When file is already an absolute name, the name is checked against the file system instead of Octave’s loadpath. In this case, if file exists it will be returned in fname, otherwise an empty string is returned.

If the first argument is a cell array of strings, search each directory of the loadpath for element of the cell array and return the first that matches.

If the second optional argument "all" is supplied, return a cell array containing the list of all files that have the same name in the path. If no files are found, return an empty cell array.

See also: file_in_path, dir_in_loadpath, path.

: restoredefaultpath ()

Restore Octave’s path to its initial state at startup.

See also: path, addpath, rmpath, genpath, pathdef, savepath, pathsep.

: command_line_path ()

Return the command line path variable.

See also: path, addpath, rmpath, genpath, pathdef, savepath, pathsep.

: dirname = dir_in_loadpath (dir)

: dirname = dir_in_loadpath (dir, "all")

Return the absolute name of the loadpath element matching dir if it can be found in the list of directories specified by path.

If no match is found, return an empty character string.

The match is performed at the end of each path element. For example, if dir is "foo/bar", it matches the path element "/some/dir/foo/bar", but not "/some/dir/foo/bar/baz" "/some/dir/allfoo/bar". When dir is an absolute name, rather than just a path fragment, it is matched against the file system instead of Octave’s loadpath. In this case, if dir exists it will be returned in dirname, otherwise an empty string is returned.

If the optional second argument is supplied, return a cell array containing all name matches rather than just the first.

See also: file_in_path, file_in_loadpath, path.