matlab.mpm.Package - MATLAB package - MATLAB (original) (raw)

MATLAB package

Since R2024b

Description

A MATLAB® package is a collection of code bundled for distribution. Use thematlab.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:

Syntax

Description

`pkg` = matlab.mpm.Package([pkgloc](#mw%5F1e581bc5-9be1-48b6-a534-ea397b5446c5)) creates a package object for the package at pkgloc.

example

Input Arguments

expand all

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 namedmpackage.json.

Properties

expand all

Package Identifiers

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

Displayed package name, specified as a string scalar.

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 example1.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>`_.

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

Package Description

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.

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

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.

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:

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

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

Folders designated asmatlab 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"]

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.

This property is read-only.

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

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.

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.

This property is read-only.

Package Status

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.

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.

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

Examples

collapse all

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

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

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 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

Version History

Introduced in R2024b

expand all

You can add Java code to MATLAB Packages. You can specify the language of package folders by setting thelanguages 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 asmatlab, MATLAB files in that folder are ignored. If a package folder is not designated as java, JAR files in that folder are ignored.