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.

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 identifier

string scalar

Package identifier, 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.

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.

Description — Package description

string scalar

Package description, specified as a string scalar.

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.

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

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

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

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

matlab.mpm.Repository object

This property is read-only.

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

Package Status

Installed — Installation status

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

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

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

Return Packages in Repositories

Create a matlab.mpm.Package array for all packages in known repositories.

pkg = mpmsearch("*")

pkg = 

  1×13 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

More About

Package Definition File

The package definition file mpackage.json contains identifying information such as the package name, version, and unique identifier, descriptive information such as a summary of the packages purpose, provider, and MATLAB release compatibility, and the properties of that package such as the status of the package, member folders, and any dependencies.

A package consists of root folder which contains the files and member folders of the package. When a package is installed, the root folders and all member folders are added to the path. The root folder contains a resources folder which contains the package definition file.

{
  "name": "DeepLearning",
  "version": "2.0.1",
  "id": "765f7f64-deba-42e2-8962-36899bd7e07f",
  "formerNames": [
    "MachineLearningPackage",
    "NeuralNetPackage"
  ],
  "displayName": "Deep Learning Toolkit",
  "summary": "An advanced toolkit for deep learning and neural network research.",
  "description": "The Deep Learning Toolkit offers a comprehensive suite of MATLAB tools for designing, training, and deploying deep learning and neural network applications. It supports a wide range of convolutional and recurrent neural network architectures, making it suitable for both academic research and industrial applications.",
  "provider": {
    "name": "John Doe",
    "organization": "The MathWorks, Inc.",
    "email": "[e-mail]",
    "url": "mathworks.com"
  },
  "folders": [
    {
      "path": "helpers"
    },
    {
      "path": "CNN"
    }
  ],
  "dependencies": [
    {
      "name": "CornersPkg",
      "compatibleVersions": "1.0.0",
      "id": "e6c4123e-0068-42be-aef2-00d49d1509f5"
    },
    {
      "name": "MATLABMath",
      "compatibleVersions": ">=3.1.0 <4.0.0",
      "id": "ec63e40a-8625-46d7-aae9-31a6a6c699e2"
    }
  ],
  "releaseCompatibility": ">=R2024b",
  "schemaVersion": "1.0.0"
}

Version History

Introduced in R2024b