mpminstall - Install package - MATLAB (original) (raw)
Install package
Since R2024b
Syntax
Description
`pkg` = mpminstall([packageFolder](#mw%5F5d7d729a-089d-4f45-96d8-d25b48770da8)) installs the specified package folder and its dependencies, adds them to the path, and returns a matlab.mpm.Package object. MATLAB® searches all folders on the MATLAB path and installs the latest version.
`pkg` = mpminstall([packageSpecifier](#mw%5Fa280e2cb-2b04-461e-8e19-ee31da47d7a8)) installs the specified package and it's dependencies and adds them to the path. By default, the function searches all known repositories and installs the latest version.
`pkg` = mpminstall([pkgArray](#mw%5F3ed4baca-5c62-4b0a-87df-535f437256ea)) installs the specified packages and their dependencies. The function copies packages and their dependencies to the default installation area. All packages specified in the argument list are added to the MATLAB path.
`pkg` = mpminstall(___,[Name=Value](#namevaluepairarguments)) specifies options using one or more name-value arguments. For example, you can specify whether to install package dependencies and whether to add the package member folders to the beginning or end of the MATLAB path.
Examples
Install the package MyPackage. When prompted, confirm the installation.
pkg = mpminstall("MyPackage")
The following packages will be installed: MyPackage@1.0.0
Do you want to continue? [YES/no]:
Copying MyPackage@1.0.0 package...Done.
Successfully added the following packages to the path: MyPackage (help)
Installation complete.
pkg =
Package with properties:
Package Definition Name: "MyPackage" DisplayName: "MyPackage" Version: 1.0.0 (1×1 Version) Summary: "" Description: "" Provider: Folders: [1×0 PackageFolder] (1×0 PackageFolder) Dependencies: "" ReleaseCompatibility: "*" FormerNames: "" ID: "bb9abc84-5324-42fd-851c-b65e2887f3b5"
Package Installation Installed: 1 Editable: 0 InstalledAsDependency: 0 PackageRoot: "C:\Users\MyProfile\AppData\Roaming\MathWorks\MATLAB Add-Ons\MyPackage@1.0.0" InstalledDependencies: "" MissingDependencies: ""
Repository Repository: [0×0 Repository]
help MyPackage
Install the package MyPackage by specifying the root folder. When prompted, confirm the installation.
pkg = mpminstall("C:\MyCode\PackageRootDir")
The following packages will be installed: MyPackage@1.0.0
Do you want to continue? [YES/no]:
Copying MyPackage@1.0.0 package...Done.
Successfully added the following packages to the path: MyPackage (help)
Installation complete.
pkg =
Package with properties:
Package Definition Name: "MyPackage" DisplayName: "MyPackage" Version: 1.0.0 (1×1 Version) Summary: "" Description: "" Provider: Folders: [1×0 PackageFolder] (1×0 PackageFolder) Dependencies: "" ReleaseCompatibility: "*" FormerNames: "" ID: "bb9abc84-5324-42fd-851c-b65e2887f3b5"
Package Installation Installed: 1 Editable: 0 InstalledAsDependency: 0 PackageRoot: "C:\Users\MyProfile\AppData\Roaming\MathWorks\MATLAB Add-Ons\MyPackage@1.0.0" InstalledDependencies: "" MissingDependencies: ""
Repository Repository: [0×0 Repository]
help MyPackage
Install the package MyPackage in authoring mode by specifying the root folder and the Authoring name-value argument. In authoring mode, the mpminstall function installs the package in its current location rather than in the default installation area and makes the package editable. When prompted, confirm the installation.
pkg = mpminstall("C:\MyCode\PackageRootDir",Authoring=true)
The following packages will be installed: MyPackage@1.0.0
Do you want to continue? [YES/no]:
Copying MyPackage@1.0.0 package...Done.
Successfully added the following packages to the path: MyPackage (help)
Installation complete.
pkg =
Package with properties:
Package Definition Name: "MyPackage" DisplayName: "MyPackage" Version: 1.0.0 (1×1 Version) Summary: "" Description: "" Provider: Folders: [1×0 PackageFolder] (1×0 PackageFolder) Dependencies: "" ReleaseCompatibility: "*" FormerNames: "" ID: "bb9abc84-5324-42fd-851c-b65e2887f3b5"
Package Installation Installed: 1 Editable: 1 InstalledAsDependency: 0 PackageRoot: "C:\MyCode\PackageRootDir" InstalledDependencies: "" MissingDependencies: ""
Repository Repository: [0×0 Repository]
help MyPackage
Input Arguments
MATLAB package folder, specified as a string array where each element contains a package root folder.
Example: “MyFolder\packageSource”
MATLAB package specifier, specified as a string array where each element contains a package specifier or a matlab.mpm.PackageSpecifier object. A valid folder matching the input takes precedence over a valid package specifier.
Example: “packageSpecifier”
Example: “packageSpecifier@1.0.0”
Example: "Pkg@1.0.1@17487be8-15e8-447b-9319-83516fc31f08"
Name-Value Arguments
Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.
Example: pkg = mpminstall(pkgArray,Prompt=true)
Display installation prompts, specified as a numeric or logical1 (true) or 0 (false). If you specify Prompt asfalse, then installation prompts are not displayed and the function automatically confirms that packages should be installed when prompted.
Example: Prompt=false
Verbosity level for displayed information, specified as one of these values:
"normal"(default) — Display informational messages during installation."quiet"— Do not display informational messages."detailed"— Display additional informational messages.
Example: Verbosity="quiet"
Install dependencies, specified as a numeric or logical 1 (true) or 0 (false). If you specify InstallDependencies as false, then the function does not install package dependencies.
Example: InstallDependencies=false
Force installation, specified as a numeric or logical 1 (true) or 0 (false). If you specify Force as true, then the function installs packages even if a dependency is not found or if the MATLAB version is not compatible with theReleaseCompatibility property of the installed package.
Example: Force=true
Allow replacement of installed version, specified as a numeric or logical1 (true) or 0 (false). If you specifyAllowVersionReplacement as true, then the function can replace any previously installed version of a package with the specified version so that only one version of the package is installed. Iffalse, then an error is thrown when the package to be installed matches an already installed package.
Example: AllowVersionReplacement=true
Install in place, specified as a numeric or logical 1 (true) or 0 (false). If you specify InPlace as true, then the function installs the package in its current location rather than copying it to the default installation area.
Inputs must be root folders when InPlace istrue.
Example: InPlace=true
Enable editable mode, specified as a numeric or logical 1 (true) or 0 (false). If you specify Editable as true, then the function installs the package in editable mode and MATLAB will recognize changes to the package definition file and member folders. InPlace must also be true.
The package to be installed must be specified as a package root folder or as amatlab.mpm.Package object created from a package root folder whenEditable is true.
Example: Editable=true
Temporary install, specified as a numeric or logical 1 (true) or 0 (false). If you specify Temporary as true, then the function installs the package only for the current MATLAB session.
Example: Temporary=true
Position on the MATLAB path, specified as "end" or"beginning". This value determines if package member folders are added to the end or beginning of the MATLAB path, respectively.
Example: PathPosition="beginning"
Enable authoring mode, specified as a numeric or logical 1 (true) or 0 (false). If you specify Authoring as true, thenEditable and InPlace are automatically set totrue and PathPosition is automatically set to"beginning".
pkgArray must be a root folder whenAuthoring is true.
Example: Authoring=true
Algorithms
When installing a package, the MATLAB Package Manager determines if a package matching the specified package ID and a version in the specified version range is already installed or on the list of packages to be installed. If not, then MATLAB searches the known repositories for available packages that meet all the following conditions:
- The package identifier matches the specified package name or ID. Package names are matched case-insensitively.
- The version is compatible with the specified version range.
- The
ReleaseCompatibilityproperty value is compatible with the MATLAB release being used.
MATLAB searches each repository on the known repository list in order. If a repository has multiple packages that meet these conditions, then MATLAB selects the package with the latest semantic version. Once a package that meets the conditions has been found, other repositories on the list of known repositories are not searched.
When installing a package, MATLAB determines required dependencies to install as well.
For each required dependency, MATLAB determines if a package matching the dependency package ID and a version compatible with the package version range is already installed or on the install list. If so, MATLAB skips the dependency and advances to the next required dependency. If not, MATLAB searches the known repositories for the dependency package following the same process as for the original package.
If a package or required dependency conflicts with an already installed package, installation will not proceed and an error will be thrown. If theAllowVersionReplacement Name-Value argument is specified astrue, then the required dependency version will replace the installed version.
If installed dependencies have their own dependencies, MATLAB follows the same process recursively until it finds and installs all required packages.
Once the MATLAB Package Manager has identified all the packages to install, MATLAB copies the files from the source to the installation area. The default installation area is the same as the add-ons installation folder. For additional information and see Default Add-On Installation Folder.
During package installation, MATLAB creates a folder in the installation area named for the package name, version, and ID. The folder name can be truncated or modified to comply with the naming conventions of the local file system.
If the package source is a folder and the package InPlace property istrue, then MATLAB does not copy the package.
After copying packages to the installation area, MATLAB registers the packages and their dependencies and adds the package root folder and all subfolders to the MATLAB path. During package registration, MATLAB adds the package root folder and all subfolders to the MATLAB path based on the PathPosition property.
Version History
Introduced in R2024b