Main Content

matlab.addons.toolbox.ToolboxOptions

Options for packaging toolbox project

Since R2023a

expand all in page

    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,Name=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.

    example

    opts = matlab.addons.toolbox.ToolboxOptions(toolboxFolder,identifier,Name=Value) sets properties using one or more 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 name-value arguments 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.

    example

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

    example

    Input Arguments

    expand all

    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"

    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"

    Toolbox project file (.prj file), specified as a string scalar or character vector. When specifying projectFile, include the relative or absolute path to the file.

    Example: "myToolbox.prj"

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

    Properties

    expand all

    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.

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

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

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

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

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

    Toolbox author company name, specified as a string scalar or 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.

    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.

    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.

    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.

    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.

    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.

    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 ("").

    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 ("").

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

    FieldDescription
    Glnxa64Whether the toolbox supports glnxa64 systems, specified as true (default) or false
    Maci64Whether the toolbox supports maci64 systems, specified as true(default) or false
    MatlabOnlineWhether the toolbox supports MATLAB Online™, specified as true (default) or false
    Win64Whether the toolbox supports win64 systems, specified as true (default) or false

    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.

    Required add-ons to be downloaded and installed during toolbox 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 toolbox is compatible with, specified as a string scalar or character vector
    LatestVersionLatest add-on version that the toolbox is compatible with, specified as string scalar or character vector
    DownloadURLURL to download the add-on, specified as a string scalar or character vector

    Additional required software packages to be downloaded and installed during toolbox 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", "maci64", 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

    Object Functions

    matlab.addons.toolbox.packageToolboxPackage toolbox project

    Examples

    collapse all

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

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

    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

    See Also

    | | | |