matlab.mpm.Package

MATLAB package

Since R2024b

Description

A MATLAB^® package is a collection of code bundled for distribution. Use the matlab.mpm.Package object to represent the package contents, dependencies, and properties. The MATLAB Package Manager uses the package object to ensure proper installation of a package and any dependencies.

If you install a package in editable mode, you can use the returned package object to modify the package properties, such as changing the attributes in the package definition file or 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.

Properties

Package Identifiers

Name — Package name

string scalar

Package name, specified as a string scalar. Name must be a valid MATLAB identifier. Package name can be used as a search criteria when using mpmsearch, mpmlist, and when resolving dependencies are considered valid matches.

DisplayName — Displayed package name

string scalar

Displayed package name, specified as a string scalar.

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 version>.<minor version>.<patch version>, 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 backwards compatibility when updating the name of a package. Packages with FormerNames that match search criteria when using mpmsearch, mpmlist, and when resolving dependencies are considered 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

string scalar

Compatible MATLAB versions, specified as a string scalar containing a valid version range. MATLAB version can be specified as the full name of a MATLAB release version, for example, "R2024b" or as a semantic version range.

A MATLAB release name follows the format:

• Ryyyy[a|b] — Where yyyy is the year of the release and a or b. For example R2024b.

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

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

• R20yy[a|b]_[Prerelease]_Update_# — Specifies the prerelease version as well as a particular update. For example R2024b_Prerelease_Update1.

MATLAB release do not follow the Semantic Versioning 2.0.0 standard. For MATLAB releases versions consists of three dot-separated numbers in the format: <release year>.<first or second release>.<update number>. When specifying MATLAB version using this version syntax, 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 update number corresponds to the update version. For example, R2024b would have a version of 24.2.0. The first update for R2025a would have a version of 25.1.1. Pre-release status is optional and is specified by adding -prerelease to the end of the version range, for example the prerelease version of R2025b would be 25.2.0-prerelease.

A version range can be specified using the <, <=, >, or >= operators in front of a version number. For example >24.2.0 would specify all versions later than R2024b. Multiple ranges separated by whitespace can be specified to further limit matches. For example, >24.2.0 <=24.2.2 would include versions between R2024b and R2024b update 2 but would not include R2025a or R2024b Update 3. Use the || operator to designate multiple acceptable version ranges. For example, <24.2.0 || >24.1.2 would include versions less than R2024b and greater than R2024b Update 2 but would not include R2024b Update 1.

Example: "R2024b"

Example: "R2024b_Prerelease"

Example: "R2024b_Update_1"

Example: "R2024b_Prerelease_Update_1"

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 Java class path, allowing Java resources to be accessible within MATLAB. (since R2025a)

Example: "functions"

Example: ["objects/publicObjects1" "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 1 or 0 of data type logical. This property is 1 if the package is installed.

InstalledAsDependency — Dependency status

Read-only: 1 | 0

This property is read-only.

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

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 the Editable name-value argument set to 1. A package must be in editable mode to modify its metadata, such as updating the version number, adding and removing subfolders, adding and removing dependencies, and so on.

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

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: <missing>
                  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\New Folder\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: <missing>
                  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

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
    InstalledAsDependency
    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
    InstalledAsDependency: 0

   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.

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

Version History

Introduced in R2024b

R2025a: Java files supported in packages

You can add Java code to MATLAB Packages. You can specify the language of package folders by setting the languages property of the matlab.mpm.PackageFolder object. When 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.