matlab.mpm.Package

MATLAB package

Since R2024b

Description

A MATLAB^® package is a collection of code bundled for distribution. Use a matlab.mpm.Package object to represent the contents, dependencies, and properties of a package. The MATLAB Package Manager uses the package object to install a package and any dependencies. If you modify a package definition file directly, the MATLAB Package Manager updates the corresponding package object accordingly.

If you install a package in editable mode (for example, by using mpminstall with the Authoring name-value argument set to true), you can use the returned package object to modify the package properties, such as adding and removing subfolders from a package. Packages that are not in editable mode cannot be modified.

Creation

There are several ways to create a matlab.mpm.Package object. Use either the matlab.mpm.Package function (described here) or one of these functions:

• Create a new package using mpmcreate.

• Install a package using mpminstall.

• Return a list of installed packages using mpmlist.

• Search for packages using mpmsearch.

Syntax

pkg = matlab.mpm.Package(pkgloc)

Description

pkg = matlab.mpm.Package(pkgloc) creates a package object for the package at pkgloc.

Input Arguments

pkgloc — Package root folder

string scalar | character vector

Package root folder, specified as a string scalar or character vector containing the absolute or relative path to the root folder. The package root folder must contain a resources subfolder that includes a package definition file named mpackage.json.

Output Arguments

pkg — Package

matlab.mpm.Package object

Package, returned as a matlab.mpm.Package object.

Properties

Package Identifiers

Use these properties to identify your package. The MATLAB Package Manager uses three pieces of information to identify and distinguish between packages: Name, Version, and ID. Some package management functions accept a package identifier or package specifier as an input. A package identifier uniquely identifies a specific package and version and presents package identifying information in the format Name@Version@ID. A package specifier specifies a range of versions for given package. Package specifiers have a similar format to package identifiers but includes syntax for expressing a range of versions rather than one specific version. For additional information, see Distinguish Between Packages Using Package Identifiers.

Name — Package name

string scalar

Package name, specified as a string scalar. Name must be a valid MATLAB identifier.

When searching for packages, such as with mpmsearch or mpmlist, or when resolving dependencies, the MATLAB Package Manager searches the names in both this Names property and the FormerNames property for valid matches.

Example: "SampleToolbox"

DisplayName — Displayed package name

string scalar

Displayed package name, specified as a string scalar. Unlike the Name property, which must be a valid MATLAB identifier, the DisplayName property is not used in code and does not need to be a valid MATLAB identifier. It can include spaces, special characters, and Unicode characters to enhance readability and provide a better understanding of the package's purpose.

Example: "My Sample Toolkit"

Version — Package version

matlab.mpm.Version object

Package version, specified as a matlab.mpm.Version object.

Version syntax follows the Semantic Versioning 2.0.0 format: <major>.<minor>.<patch>, where each version number must be a nonnegative integer, for example, 1.2.3. You can optionally specify a pre-release version by adding -<pre-release version> to the end of the version, for example, 1.2.3-alpha. Optionally specify a build version by adding +<build version>.

ID — Package UUID

string scalar

Package UUID, specified as a string scalar containing a universally unique identifier (UUID).

Package Description

FormerNames — Previous package names

string array

Previous package names, specified as a string array. Use this property to record previous names of the package and ensure backward compatibility when updating the name of a package.

When searching for packages, such as with mpmsearch or mpmlist, or when resolving dependencies, the MATLAB Package Manager searches the names in both this FormerNames property and the Names property for valid matches.

Provider — Package provider

matlab.mpm.Provider object

Package provider, specified as a matlab.mpm.Provider object.

Summary — Package summary

string scalar

Package summary, specified as a string scalar. The summary field serves as a concise description of a MATLAB package.

Description — Package description

string scalar

Package description, specified as a string scalar. The description provides a detailed explanation of a MATLAB package, elaborating on its functionality, use cases, and any other relevant information that can help users understand what the package does and how it can be utilized.

releaseCompatibility — Compatible MATLAB versions

JSON string

Compatible MATLAB versions, specified as a JSON string containing a valid version range. Specify a MATLAB version as the full name of a MATLAB release (for example, "R2024b"), a range of MATLAB releases (for example, "R2024b - R2025b"), or as a semantic version range (for example, ">R2024b").

A MATLAB release name follows the format:

• The release, where R20yy[a|b] — Where 20yy is the year of the release and either a or b. For example, R2024b.

• R20yy[a|b]_[Prerelease] — The prerelease version. For example, R2024b_Prerelease.

• R20yy[a|b]_Update_# — A particular update. For example, R2024b_Update_1.

• R20yy[a|b]_[Prerelease]_Update_# — The prerelease version as well as a particular update. For example, R2024b_Prerelease_Update_1.

MATLAB releases do not follow the Semantic Versioning 2.0.0 standard. Instead, specify a MATLAB release using three dot-separated numbers in the format <release year>.<first or second release>.<update number>.

• The first number is equal to the last two digits of the release year.

• The second number is 1 for "a" releases and 2 for "b" releases.

• The third number corresponds to the update version.

For example, R2024b has a version of 24.2.0. The first update for R2025a has a version of 25.1.1. Optionally specify a prerelease status by adding -prerelease to the end of the version. For example, the prerelease version of R2025b is 25.2.0-prerelease.

You can specify a version range by using the <, <=, >, or >= operators in front of a version number. For example, >24.2.0 specifies all versions later than R2024b. You can specify multiple ranges separated by white space to further limit matches. For example, >24.2.0 <=24.2.2 includes versions between R2024b and R2024b Update 2 but does not include R2024b or R2024b Update 3. Use the || operator to designate multiple acceptable version ranges. For example, <24.2.0 || >24.2.2 includes versions earlier than R2024b and later than R2024b Update 2 but does not include R2024b Update 1.

Example: "R2024b"

Example: "R2024b_Prerelease"

Example: "R2024b_Update_1"

Example: "R2024b_Prerelease_Update_1"

Example: "R2024b - R2025b"

Example: "24.2.0"

Example: "24.2.1"

Example: "24.2.0-prerelease"

Example: ">=R2024b"

Example: ">24.2.0"

Example: "<24.2.0 || >24.1.2"

Package Folders and Dependencies

Folders — Package member folders

matlab.mpm.PackageFolder array

Package member folders, specified as a matlab.mpm.PackageFolder array where each element represents a subfolder.

Folders designated as matlab are automatically added to the MATLAB search path when the package is installed. Folders designated as java are added to the dynamic and static Java class path, allowing Java resources to be accessible within MATLAB. (since R2025a)

Example: matlab.mpm.PackageFolder("functions")

Example: [matlab.mpm.PackageFolder("objects/publicObjects1") matlab.mpm.PackageFolder("objects/publicObjects2")]

Dependencies — Package dependencies

matlab.mpm.Dependency array

Package dependencies, specified as a matlab.mpm.Dependency array. Package dependencies are other packages that the package depends on. If a package has no dependencies, then this property contains an empty string.

PackageRoot — Package root folder

Read-only: string scalar

This property is read-only.

Package root folder, returned as a string scalar containing the absolute path to the root folder.

MissingDependencies — Missing package dependencies

Read-only: matlab.mpm.Dependency array

This property is read-only.

Missing package dependencies, returned as a matlab.mpm.Dependency array. This property represents dependencies of the package that are not installed. If no dependencies are missing, then this property contains an empty string.

InstalledDependencies — Installed package dependencies

Read-only: matlab.mpm.Dependency array

This property is read-only.

Installed package dependencies, returned as a matlab.mpm.Dependency array. This property represents dependencies of the package that are installed. If no dependencies are installed, then this property contains an empty string.

Repository — Package repository

Read-only: matlab.mpm.Repository object

This property is read-only.

Package repository, returned as a matlab.mpm.Repository object.

Package Status

Installed — Installation status

Read-only: 1 | 0

This property is read-only.

Installation status, returned as a 1 or 0 of data type logical. This property is 1 if the package is installed.

DirectlyInstalled — Dependency status

Read-only: 1 | 0

Since R2026a

This property is read-only.

Dependency status, returned as a 1 or 0 of data type logical. This property is 1 if the package was installed directly and 0 if the package was installed as a dependency for a different package.

Before R2026a: The matlab.mpm.Package object had a read-only property named InstalledAsDependency, which had a value of 1 if the package was installed as a dependency for a different package, and 0 otherwise.

Editable — Editable status

Read-only: 1 | 0

This property is read-only.

Editable status, returned as a 1 or 0 of data type logical. This property is 1 when the package is in editable mode.

To make the package editable, use the mpminstall function with both the Editable and InPlace name-value arguments set to true, or with the Authoring name-value argument set to true. A package must be in editable mode to modify its metadata, such as updating the version number, adding and removing subfolders,or adding and removing dependencies.

This property is 1 for an uninstalled package that is not in a repository. This property is 0 for an uninstalled package in a repository.

Object Functions

addFolder	Add member folder to package
removeFolder	Remove member folder from package
addDependency	Add dependency to package
removeDependency	Remove dependency from package
updateDependency	Update dependency information
digest	Generate cryptographic hash for package
PackageIdentifier	Create package identifier

Examples

Create Package

Create a new package named MyPackage from the folder PackageRootDir.

pkg = mpmcreate("MyPackage","PackageRootDir")

pkg = 

  Package with properties:

   Package Definition
                     Name: "MyPackage"
              DisplayName: "MyPackage"
                  Version: 1.0.0 (1×1 Version)
                  Summary: ""
              Description: ""
                 Provider: "" (1×1 Provider)
                  Folders: [1×0 PackageFolder] (1×0 PackageFolder)
             Dependencies: ""
     ReleaseCompatibility: ""
              FormerNames: [1×0 string]
                       ID: "bb9abc84-5324-42fd-851c-b65e2887f3b5"

   Package Installation
                Installed: 1
                 Editable: 1
        DirectlyInstalled: 1
              PackageRoot: "C:\MyCode\PackageRootDir"
    InstalledDependencies: ""
      MissingDependencies: ""

   Repository
               Repository: [0×0 Repository]

  help MyPackage

Install Package

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: "" (1×1 Provider)
                  Folders: [1×0 PackageFolder] (1×0 PackageFolder)
             Dependencies: ""
     ReleaseCompatibility: ""
              FormerNames: [1×0 string]
                       ID: "bb9abc84-5324-42fd-851c-b65e2887f3b5"

   Package Installation
                Installed: 1
                 Editable: 0
        DirectlyInstalled: 1
              PackageRoot: "C:\Users\MyProfile\AppData\Roaming\MathWorks\MATLAB Add-Ons\MyPackage@1.0.0"
    InstalledDependencies: ""
      MissingDependencies: ""

   Repository
               Repository: [0×0 Repository]

  help MyPackage

Return Installed Packages

Create a matlab.mpm.Package array for all installed packages.

pkg = mpmlist

pkg = 

  1×3 Package array with properties:

    Name
    DisplayName
    FormerNames
    Version
    ID
    Dependencies
    Provider
    Folders
    Summary
    Description
    ReleaseCompatibility
    Installed
    Editable
    DirectlyInstalled
    PackageRoot
    Repository
    InstalledDependencies
    MissingDependencies

  Display as table

Create Package Object for Existing Package

Create a matlab.mpm.Package object for the package in the MyPackage folder.

pkg = matlab.mpm.Package("MyPackage")

pkg = 
  Package with properties:

   Package Definition
                     Name: "MyPackage"
              DisplayName: "MyPackage"
                  Version: 1.0.0 (1×1 Version)
                  Summary: ""
              Description: ""

   Package Installation
                Installed: 1
        DirectlyInstalled: 1

   Repository
               Repository: [0×0 Repository]

  Show all properties

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

The matlab.mpm.Package function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2024b

R2026a: InstalledAsDependency property replaced by DirectlyInstalled property

The InstalledAsDependency property has been removed. To determine if a package was installed directly or installed as a dependency of another package, use the new DirectlyInstalled property. For example, if a package was installed as a dependency of another package, the DirectlyInstalled property is 0, while the removed InstalledAsDependency property would have been 1.

R2025a: Java files supported in packages

You can add Java code to MATLAB packages. When you add a package folder with Java code to the package object by setting its Folders property, also set the Languages property of the matlab.mpm.PackageFolder object you specify to "java". When a package is installed, all Java resources in a folder designated as java are added to both the dynamic and static class path.

If the Languages property of a package folder is not designated as matlab, MATLAB files in that folder are ignored. If a package folder is not designated as java, JAR files in that folder are ignored.