matlab.addons.toolbox.ToolboxOptions

Options for packaging toolbox project

Since R2023a

Description

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

Creation

Syntax

opts = matlab.addons.toolbox.ToolboxOptions(toolboxFolder,identifier)

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

opts = matlab.addons.toolbox.ToolboxOptions(projectFile)

Description

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

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

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

When setting properties for a toolbox 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.

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

Input Arguments

toolboxFolder — Toolbox folder

string scalar | character vector

Toolbox folder containing the files for the toolbox, specified as a string scalar or character vector. When specifying toolboxFolder, include the relative or absolute path to the folder.

Example: "C:\Work\myToolboxFolder"

identifier — Unique identifier of toolbox

string scalar | character vector

Unique identifier of the toolbox, specified as a string scalar or character vector.

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

If you want to share your toolbox on MATLAB File Exchange, 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.

To get the unique identifier for an existing installed toolbox, 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"

Example: "testUuid"

projectFile — Project file

string scalar | character vector

Project file (.prj), 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 toolbox task. (since R2025a)

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

Example: "myToolbox.prj"

Example: "C:\Work\myOtherToolbox.prj"

Properties

ToolboxName — Toolbox name

string scalar | character vector

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

ToolboxVersion — Version number of installed application

"1.0" (default) | string scalar | character vector

Version number of the installed application, specified as a string scalar or character vector. Enter the version number in the major.minor.bug.build format. bug and build are optional.

Description — Detailed toolbox description

"" (default) | string scalar | character vector

Detailed toolbox description, specified as a string scalar or character vector.

Summary — Summary description of toolbox

"" (default) | string scalar | character vector

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

AuthorName — Toolbox author name

"" (default) | string scalar | character vector

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

AuthorEmail — Toolbox author email address

"" (default) | string scalar | character vector

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

AuthorCompany — Toolbox author company name

"" (default) | string scalar | character vector

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

ToolboxImageFile — Path to toolbox image file

string scalar | character vector

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

ToolboxFiles — Files to be packaged

string vector | character vector | cell array of character vectors

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

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.

ToolboxMatlabPath — Folders to add to MATLAB path

string vector | character vector | cell array of character vectors

Folders to add to MATLAB path during toolbox 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.

AppGalleryFiles — Toolbox apps gallery files

string vector | character vector | cell array of character vectors

Toolbox 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 toolbox installation. When specifying AppGalleryFiles, include the relative or absolute paths to the files.

Files included in AppGalleryFiles must also be included in ToolboxFiles.

ToolboxGettingStartedGuide — Path to toolbox Getting Started Guide

string scalar | character vector

Path to the toolbox 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 toolbox. The path can be a relative path or an absolute path.

OutputFile — Path to toolbox output file

string scalar | character vector

Path to the toolbox 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.

MaximumMatlabRelease — Latest compatible MATLAB release

string scalar | character vector

Latest MATLAB release that the toolbox 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 ("").

MinimumMatlabRelease — Earliest compatible MATLAB release

string scalar | character vector

Earliest MATLAB release that the toolbox 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 ("").

SupportedPlatforms — Platforms that the toolbox supports

scalar struct

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

Field	Description
Glnxa64	Whether the toolbox supports glnxa64 systems, specified as true (default) or false
Maci64	Whether the toolbox supports maci64 systems, specified as true(default) or false
MatlabOnline	Whether the toolbox supports MATLAB Online™, specified as true (default) or false
Win64	Whether the toolbox supports win64 systems, specified as true (default) or false

ToolboxJavaPath — Files to add to Java class path

string vector | character vector | cell array of character vectors

Files to add to the Java class path during toolbox 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.

RequiredAddons — Required add-ons

struct vector

Required add-ons to be downloaded and installed during toolbox installation, specified as a struct vector with these fields.

Field	Description
Name	Name of required add-on, specified as a string scalar or character vector
Identifier	Unique identifier of the add-on, specified as a string scalar or character vector
EarliestVersion	Earliest add-on version that the toolbox is compatible with, specified as a string scalar or character vector
LatestVersion	Latest add-on version that the toolbox is compatible with, specified as string scalar or character vector
DownloadURL	URL to download the add-on, specified as a string scalar or character vector

RequiredAdditionalSoftware — Additional required software packages

struct vector

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

Field	Description
Name	Name of software package, specified as a string scalar or character vector
Platform	Platform to download the additional software package for, specified as "win64", "maci64", or "glnxa64"
DownloadURL	URL to download the additional software package, specified as a string scalar or character vector
LicenseURL	URL for the software package license file, specified as a string scalar or character vector

Object Functions

matlab.addons.toolbox.packageToolbox

Package toolbox project

Examples

Package Toolbox with Specified Packaging Options

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

identifier = "myToolboxUuid";
toolboxFolder = "C:\Work\myToolbox";
opts = matlab.addons.toolbox.ToolboxOptions(toolboxFolder,identifier);

opts.ToolboxName = "My Toolbox";
 
opts.SupportedPlatforms.Win64 = true;
opts.SupportedPlatforms.Maci64 = false;
opts.SupportedPlatforms.Glnxa64 = true;
opts.SupportedPlatforms.MatlabOnline = true;

opts.MinimumMatlabRelease = "R2017b";
opts.MaximumMatlabRelease = "";

opts.RequiredAddons = ...
    struct("Name","Gui Layout Toolbox", ...
           "Identifier","e5af5a78-4a80-11e4-9553-005056977bd0", ...
           "EarliestVersion","1.0", ...
           "LatestVersion","4.0", ...
           "DownloadURL","");

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

Package App with Specified Packaging Options

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

appUuid = "myAppUuid";
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);

Package Toolbox from Project File

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

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

Version History

Introduced in R2023a

R2025a: Specify projectFile as MATLAB project that contains toolbox task

You can now create a ToolboxOptions object by specifying projectFile as a MATLAB project file that contains a toolbox task. For more information, see Create and Share Toolboxes.

Previously, projectFile supported only toolbox project files.