matlab.addons.toolbox.ToolboxOptions

R2026b

Options for building a package

Since R2023a

expand all in page

    Description

    Use ToolboxOptions to specify custom options when building a package. After you create a ToolboxOptions object, use the matlab.addons.toolbox.packageToolbox function to build the package.

    Creation

    Syntax

    opts = matlab.addons.toolbox.ToolboxOptions(packageFolder,identifier)
    opts = matlab.addons.toolbox.ToolboxOptions(packageFolder,identifier,PropertyName=Value)
    opts = matlab.addons.toolbox.ToolboxOptions(projectFile)

    Description

    opts = matlab.addons.toolbox.ToolboxOptions(packageFolder,identifier) creates a ToolboxOptions object using the files in the specified package folder and the specified unique identifier.

    If the package folder contains a package definition file, matlab.addons.toolbox.ToolboxOptions uses information from the package such as the description, summary, and package name to set properties of the ToolboxOptions object. For more information about packages, see MATLAB Packages and Package Dependencies.

    example

    opts = matlab.addons.toolbox.ToolboxOptions(packageFolder,identifier,PropertyName=Value) specifies one or more property values using name-value arguments. For example, matlab.addons.toolbox.ToolboxOptions(packageFolder,identifier,MaximumMatlabRelease="R2023a") sets the latest MATLAB® release with which the package is compatible to R2023a.

    When setting properties for a package containing a package definition file, matlab.addons.toolbox.ToolboxOptions uses the values of the specified name-value arguments instead of the information from the package to set properties.

    example

    opts = matlab.addons.toolbox.ToolboxOptions(projectFile) creates a ToolboxOptions object using the information in the specified package project file (.prj or .toml).

    example

    Input Arguments

    expand all

    Folder containing the files for the package, specified as a string scalar or character vector. When specifying packageFolder, include the relative or absolute path to the folder.

    Example: "C:\Work\myPackageFolder"

    Unique identifier of the package, specified as a string scalar or character vector. identifier must follow the RFC 4122 specification which defines a Uniform Resource Name namespace for UUIDs (Universally Unique Identifier). For more information, see https://www.rfc-editor.org/info/rfc4122.

    In addition, identifier must be the same across all versions of the package. Otherwise, MATLAB installs each version of the package as a new package instead of a new version of the package. If the package folder contains a package definition file, mpackage.json, identifier must be the same as the identifier defined in the package.

    To get the unique identifier for an existing installed package, use the matlab.addons.installedAddons function. For example:

    addons = matlab.addons.installedAddons
    addons =

  1×4 table

             Name                   Version     Enabled                 Identifier              
    ___________________________    _________    _______    ______________________________________

    "Random File Name Creator"       "1.0"       true      "75442144-f751-4011-bf0e-32b6fb2f1433"

    Example: "e5af5a78-4a80-11e4-9553-005056977bd0"

    Project file (.prj or .toml), specified as a string scalar or character vector. When specifying projectFile, include the relative or absolute path to the file. The specified MATLAB project must contain exactly one package task. (since R2025a)

    For a package created before R2025a, you can specify projectFile as the package project file (.prj).

    Example: "myPackage.prj"

    Example: "C:\Work\myOtherPackage.toml"

    Properties

    expand all

    Package display name, specified as a string scalar or character vector. If you do not specify ToolboxName, then MATLAB derives the name from the package folder name.

    When a package is installed, ToolboxName provides the value for the displayName property of the corresponding mpackage.json file.

    Since R2026b

    Package name, specified as a string scalar or character vector. PackageName must be a valid MATLAB identifier. If you do not specify PackageName, then MATLAB derives the name from the package folder name.

    When a package is installed, PackageName provides the value for the name property of the corresponding mpackage.json file.

    Version number of the installed application, specified as a string scalar or character vector containing a valid semantic version.

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

    When a package is installed, ToolboxVersion provides the value for the version property of the corresponding mpackage.json file.

    Summary description of the package, specified as a string scalar or character vector.

    When a package is installed, Summary provides the value for the summary property of the corresponding mpackage.json file.

    Since R2026b

    Path to Readme file, specified as a string scalar or character vector. Use this Readme file to provide information for users on how to use your package.

    When a package is installed, Readme provides the value for the readme property of the corresponding mpackage.json file.

    Before R2026b: Use the Description property to store information on how to use your package.

    Package author name, specified as a string scalar or character vector.

    When a package is installed, AuthorName provides the value for the name subproperty of the provider property of the corresponding mpackage.json file.

    Package author email address, specified as a string scalar or character vector.

    When a package is installed, AuthorEmail provides the value for the email subproperty of the provider property of the corresponding mpackage.json file.

    Package author company name, specified as a string scalar or character vector.

    When a package is installed, AuthorCompany provides the value for the organization subproperty of the provider property of the corresponding mpackage.json file.

    Path to the package image file, specified as a string scalar or character vector. The path can be a relative path or an absolute path.

    Files to be packaged in the package, specified as a character vector, string vector, or cell array of character vectors. By default, ToolboxFiles contains the list of all files in packageFolder.

    When specifying ToolboxFiles, include the relative or absolute paths to the files. If you specify a folder, MATLAB adds all of the files in the folder to ToolboxFiles.

    Folders to add to MATLAB path during package installation, specified as a string vector, character vector, or cell array of character vectors. When specifying ToolboxMatlabPath, include the relative or absolute paths to the folders.

    Package apps gallery files, specified as a string vector, character vector, or cell array of character vectors. Apps gallery files are MATLAB executable files (.m, .mex, .mlx, .mlapp, .p) to add to apps gallery during package installation. When specifying AppGalleryFiles, include the relative or absolute paths to the files.

    Files included in AppGalleryFiles must also be included in ToolboxFiles.

    Path to the package Getting Started Guide, specified as a string scalar or character vector. The Getting Started Guide is a MATLAB code file (.m, .mlx) containing a quick start guide for your package. The path can be a relative path or an absolute path.

    Path to the package output file, specified as a string scalar or character vector. The path can be a relative path or an absolute path. If the file does not have a .mltbx extension, MATLAB appends the extension automatically when it creates the file.

    Latest MATLAB release that the package is compatible with, specified as a string scalar or character vector using the format RXXXXx, for example, "R2023a". If there is no maximum restriction, specify MaximumMatlabRelease as empty ("").

    When a package is installed, MaximumMatlabRelease and MinimumMatlabRelease are used to generate the value for the releaseCompatibility property of the corresponding mpackage.json file.

    Earliest MATLAB release that the package is compatible with, specified as a string scalar or character vector using the format RXXXXx, for example, "R2020a". If there is no minimum restriction, specify MinimumMatlabRelease as empty ("").

    When a package is installed, MaximumMatlabRelease and MinimumMatlabRelease are used to generate the value for the releaseCompatibility property of the corresponding mpackage.json file.

    Platforms that the package supports, specified as a scalar struct with these fields.

    FieldDescription
    Glnxa64Whether the package supports glnxa64 systems, specified as true (default) or false
    MacWhether the package supports Mac systems, specified as true(default) or false
    MatlabOnlineWhether the package supports MATLAB Online™, specified as true (default) or false
    Win64Whether the package supports win64 systems, specified as true (default) or false

    When a package is installed, SupportedPlatforms provides the value for the supportedPlatforms property of the corresponding mpackage.json file.

    Files to add to the Java class path during package installation, specified as a string vector, character vector, or cell array of character vectors. When specifying ToolboxJavaPath, include the relative or absolute paths to the files.

    When a package is installed, files in ToolboxJavaPath are added to the folders property of the corresponding mpackage.json file.

    Since R2026b

    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.

    Before R2026b: Use the RequiredAddons property to specify other add-ons to be downloaded and installed during package installation, specified as a struct vector with these fields:

    FieldDescription
    NameName of required add-on, specified as a string scalar or character vector
    IdentifierUnique identifier of the add-on, specified as a string scalar or character vector
    EarliestVersionEarliest add-on version that the package is compatible with, specified as a string scalar or character vector
    LatestVersionLatest add-on version that the package is compatible with, specified as string scalar or character vector
    DownloadURLURL to download the add-on, specified as a string scalar or character vector

    When a package is installed, files in PackageDependencies are added to the dependencies property of the corresponding mpackage.json file.

    Additional required software packages to be downloaded and installed during package installation, specified as a struct vector with these fields.

    FieldDescription
    NameName of software package, specified as a string scalar or character vector
    PlatformPlatform to download the additional software package for, specified as "win64", "mac", or "glnxa64"
    DownloadURLURL to download the additional software package, specified as a string scalar or character vector
    LicenseURLURL for the software package license file, specified as a string scalar or character vector

    Since R2026b

    Enable license BSD, specified as false (0) or true (1). Set this property to true to add a BSD license to the package during packaging. The BSD license includes the author company (or author name if no company is set) and the current year.

    UseLicenseBSD must be true for package files (.mltbx) uploaded to File Exchange.

    Since R2026b

    Custom labels, specified as a string array where each element contains a custom label. Use this property to add labels to make your package more easily searchable.

    When a package is installed, Tags provides the value for the tags property of the corresponding mpackage.json file.

    Since R2026b

    MathWorks product dependencies, specified as a string array where each element contains the name of a MathWorks product. Product names must be an exact match. Use ver to list all installed products.

    Object Functions

    matlab.addons.toolbox.packageToolboxBuild package from project file

    Examples

    collapse all

    Use a ToolboxOptions object to build a package named My Package that is supported on all platforms except macOS and is compatible with R2026b and later releases. The package also has one required add-on and one required additional software package.

    identifier = "a3d07955-9c3d-4ff5-8c75-7ddcff3c759e";
packageFolder = "C:\Work\myPackage";
opts = matlab.addons.toolbox.ToolboxOptions(packageFolder,identifier);

opts.ToolboxName = "My Package";
 
opts.SupportedPlatforms.Win64 = true;
opts.SupportedPlatforms.Mac = false;
opts.SupportedPlatforms.Glnxa64 = true;
opts.SupportedPlatforms.MatlabOnline = true;

opts.MinimumMatlabRelease = "R2026b";
opts.MaximumMatlabRelease = "";

opts.PackageDependencies = matlab.mpm.Dependency(...
           "Gui Layout Toolbox", ...
           ">=4.2.0", ... 
           "e5af5a78-4a80-11e4-9553-005056977bd0");

opts.RequiredAdditionalSoftware = ...
    struct("Name","Dataset", ...
           "Platform","glnxa64", ...
           "DownloadURL","https://github.com/myusername/myproject/data.zip", ...
           "LicenseURL","https://github.com/myusername/myproject/LICENSE");

matlab.addons.toolbox.packageToolbox(opts);

    Use a ToolboxOptions object to build an app named My App and add the app to the apps gallery during app installation.

    appUuid = "e4a1c2b9-7f3a-41b2-8e6d-2f9a4c1b7e5f";
appFolder = pwd;
appFile = fullfile(pwd,"myApp.m");
opts = matlab.addons.toolbox.ToolboxOptions(appFolder,appUuid,ToolboxName="My App", ...
       ToolboxFiles=appFile,AppGalleryFiles=appFile,ToolboxMatlabPath={"."});

matlab.addons.toolbox.packageToolbox(opts);

    Use a ToolboxOptions object to build a package from a project file.

    projectFile = "myPackage.prj";
opts = matlab.addons.toolbox.ToolboxOptions(projectFile);
matlab.addons.toolbox.packageToolbox(opts);

    Version History

    Introduced in R2023a

    expand all

    See Also

    | | | |

    Topics