RunMat
GitHub

View all functions

CategoryIo: Repl Fs

What does the savepath function do in MATLAB / RunMat?

savepath writes the current MATLAB search path to a pathdef.m file so that future sessions can restore the same ordering. The file is a MATLAB function that returns the path character vector, matching MathWorks MATLAB semantics.

How does the savepath function behave in MATLAB / RunMat?

  • savepath() with no inputs writes to the default RunMat location ($HOME/.runmat/pathdef.m on Linux/macOS, %USERPROFILE%\.runmat\pathdef.m on Windows). The directory is created automatically when required.
  • savepath(file) writes to the specified file. Relative paths are resolved against the current working directory, ~ expands to the user's home folder, and supplying a directory (with or without a trailing separator) appends the standard pathdef.m filename automatically.
  • The function does not modify the in-memory search path - it only writes the current state to disk. Callers can therefore continue editing the path after saving without interference.
  • status = savepath(...) returns 0 on success and 1 when the file cannot be written. [status, message, messageID] = savepath(...) returns MATLAB-style diagnostics describing the failure. Both message outputs are empty on success.
  • Invalid argument types raise savepath: filename must be a character vector or string scalar. Empty filenames raise savepath: filename must not be empty.
  • When the RUNMAT_PATHDEF environment variable is set, the zero-argument form uses that override instead of the default location.

savepath Function GPU Execution Behaviour

savepath runs entirely on the host. If callers supply a GPU-resident string, RunMat gathers it back to CPU memory before resolving the target path. No acceleration provider hooks or kernels are required.

GPU residency in RunMat (Do I need gpuArray?)

No. Because savepath interacts with the filesystem, GPU residency provides no benefit. The builtin automatically gathers GPU text inputs so existing scripts continue to work even if they accidentally construct filenames on the device.

Examples of using the savepath function in MATLAB / RunMat

Save The Current Search Path To The Default Location

status = savepath();

Expected output:

status =
     0

Persist A Project-Specific Pathdef File

status = savepath("config/project_pathdef.m");

Expected output:

status =
     0

Capture Status, Message, And Message ID

[status, message, messageID] = savepath("config/pathdef.m");
if status ~= 0
    warning("Failed to save the path: %s (%s)", message, messageID);
end

Append Genpath Output And Persist The Result

tooling = genpath("third_party/toolchain");
addpath(tooling, "-end");
savepath();

Save A Pathdef Using A Directory Argument

mkdir("~/.runmat/projectA");
savepath("~/.runmat/projectA/");

Expected behavior:

% Creates ~/.runmat/projectA/pathdef.m with the current search path.

Override The Target File With RUNMAT_PATHDEF

setenv("RUNMAT_PATHDEF", fullfile(tempdir, "pathdef-dev.m"));
savepath();

Expected behavior:

% The file tempdir/pathdef-dev.m now contains the MATLAB path definition.

Use gpuArray Inputs Transparently

status = savepath(gpuArray("pathdefs/pathdef_gpu.m"));

Expected output:

status =
     0

Inspect The Generated pathdef.m File

savepath("toolbox/pathdef.m");
type toolbox/pathdef.m;

Expected behavior:

% Displays the MATLAB function that reproduces the saved search path.

FAQ

  • Where does savepath write by default? RunMat uses $HOME/.runmat/pathdef.m (Linux/macOS) or %USERPROFILE%\.runmat\pathdef.m (Windows). Set RUNMAT_PATHDEF to override this location.
  • Does savepath create missing folders? Yes. When the parent directory does not exist, RunMat creates it automatically before writing the file.
  • What happens if the file is read-only? savepath returns status = 1 together with the diagnostic message and message ID MATLAB:savepath:cannotWriteFile. The existing file is left untouched.
  • Does savepath modify the current path? No. It only writes out the path. Use addpath, rmpath, or path to change the in-memory value.
  • Are argument types validated? Yes. Inputs must be character vectors or string scalars. String arrays with multiple elements and numeric arrays raise an error.
  • Is the generated file MATLAB-compatible? Yes. RunMat writes a MATLAB function named pathdef that returns the exact character vector stored by the path builtin, so MathWorks MATLAB and RunMat can both execute it.
  • How do I restore the path later? Evaluate the generated pathdef.m (for example by calling run('~/pathdef.m')) and pass the returned value to path(). Future RunMat releases will load the default file automatically.
  • Can I store multiple path definitions? Absolutely. Call savepath with different filenames for each profile, then run the desired file to switch.
  • Is savepath safe to call concurrently? The builtin serializes through the filesystem. When multiple sessions write to the same path at once, the last write wins - this matches MATLAB's behavior.
  • Does savepath include the current folder (pwd)? The file mirrors the output of the path builtin, which omits the implicit current folder exactly as MATLAB does.

See Also

path, addpath, rmpath, genpath

Source & Feedback