Main Content

Create and Share Toolboxes

You can package MATLAB® files to create a toolbox to share with others. These files can include MATLAB code, data, apps, examples, and documentation. When you create a toolbox, MATLAB generates a single installation file (.mltbx) that enables you or others to install your toolbox.

Create Toolbox

To create a toolbox installation file:

  1. In the Environment section of the Home tab, select Package Toolbox from the Add-Ons menu.

  2. In the Package a Toolbox dialog box, click the plus button and select your toolbox folder. It is good practice to create the toolbox package from the folder level above your toolbox folder. The .mltbx toolbox file contains information about the path settings for your toolbox files and folders. By default, any of the included folders and files that are on your path when you create the toolbox appear on their paths after the end users install the toolbox.

  3. In the dialog box, add the following information about your toolbox.

    If your toolbox folder contains a package definition file, MATLAB uses the package information such as the description, summary, and toolbox name to automatically prepopulate some of the toolbox information fields. You can then further edit these fields. For more information about packages, see Create and Manage Packages.

    Toolbox Information FieldDescription
    Toolbox Name

    Enter the toolbox name, if necessary. By default, the toolbox name is the name of the toolbox folder. The Toolbox Name becomes the .mltbx file name.

    Version

    Enter the toolbox version number in the Major.Minor.Bug.Build format. Bug and Build are optional.

    Author Name, Email, and Company

    Enter contact information for the toolbox author. To save the contact information, click Set as default contact.

    Toolbox Image

    To select an image that represents your toolbox, click Select toolbox image.

    Summary and Description

    Enter the toolbox summary and description. It is good practice to keep the Summary text brief and to add detail to the Description text.

  4. To ensure MATLAB detects the expected components, review the toolbox contents. The following sections of the Package a Toolbox dialog box appear after you select a toolbox folder.

    Package a Toolbox Dialog Box SectionDescription
    Toolbox Files and Folders

    List of the folders and files contained in your toolbox. The listed files and folders are only those files that are located in the top level of the toolbox folder. You cannot navigate through the folders in the Toolbox Packaging dialog box.

    By default, if your toolbox contains a P-code file and a MATLAB code file (.m) with the same name in the same folder, MATLAB excludes the .m file from the toolbox. To include both the .p and .m files, clear the Exclude MATLAB script or function files with matching P-files option.

    To exclude other files or folders from the toolbox, register them in the text file that is displayed when you click Exclude files and folders. It is good practice to exclude any source control files related to your toolbox.

    Requirements

    Add-ons — List of add-ons required for your toolbox. Selected add-ons are downloaded and installed when the toolbox is installed. MATLAB auto-populates this list with the add-ons it thinks the toolbox requires and selects them all by default. You can choose to omit any add-ons you do not want to install with your toolbox.

    If MATLAB is unable to find the installation information for an add-on in the list, you must enter a download URL. The download URL is the location where MATLAB can download and install the add-on. When the toolbox is installed, MATLAB installs the add-on using the specified URL.

    External Files — List of the files required for your toolbox that are located outside the toolbox folder. MATLAB auto-populates this list with the files it thinks the toolbox requires and selects them all by default. You can choose to omit any files you do not want in your toolbox.

    Install Actions

    MATLAB Path — List of folders that are added to the user’s MATLAB path when they install a toolbox. By default, the list includes any of the toolbox folders that are on your path when you create the toolbox. You can exclude folders from being added to the user’s path by clearing them from the list. To manage the path for when a toolbox is installed, click Manage the current MATLAB path. To reset the list to the default list, click Reset to the current MATLAB path.

    Java Class Path — List of Java® files that are added to the user’s Java class path when they install a toolbox. Upon toolbox installation, the JAR files are added to the dynamic path for the duration of the MATLAB session. When the toolbox user restarts MATLAB, the JAR files are added to the static path.

    Installation of Additional Software — List of additional software ZIP files that are installed on the user's system when they install a toolbox.

    Specify these fields:

    • Display Name — The name to display to the user when they install a toolbox.

    • License URL — The URL of the additional software license agreement to display to the user when they install a toolbox. The user is prompted to review and agree to the license agreement during installation. You must specify a valid URL to the license agreement.

    • Download URL — The URL to the ZIP file that contains the additional software. To specify different download URLs for different platforms, select a platform name from the drop-down menu to the left of the download URL. Then, click Add Platform to add a download URL for additional platforms.

    When the user installs a toolbox, MATLAB installs all additional software in the addons\Toolboxes\AdditionalSoftware folder, where addons is the add-ons default installation folder. For more information about the location of the add-ons default installation folder, see Get and Manage Add-Ons.

    If your toolbox contains code that refers to the installation folder of the specified additional software, make these references portable to other computers. Replace the references with calls to the generated function toolboxname\getInstallationLocation.mlx, where toolboxname is the name of your toolbox. For example, if you are creating a toolbox called mytoolbox and want to reference the install location for additional software called mysoftware, replace this code

    mysoftwarelocation = 'C:\InstalledSoftware\mysoftware\'
    with this code:
    mysoftwarelocation = mytoolbox.getInstallationLocation('mysoftware')
    To enable testing of the toolbox on your computer before packaging the toolbox, click the toolboxname\getInstallationLocation.mlx link at the bottom of the Installation of Additional Software section and enter the installed location of each additional piece of software on your computer.

    Toolbox Portability

    MATLAB uses the information in the Toolbox Portability section when the user installs the toolbox. If the compatibility check fails because the user has an unsupported platform or MATLAB version, MATLAB displays a warning. However, the user still can install the toolbox.

    Platform Compatibility — List of platforms that support the toolbox. Consider if your toolbox has third-party software or hardware requirements that are platform specific. MATLAB Online™ cannot interact with hardware, including devices used for image acquisition and instrument control.

    Release Compatibility — List of MATLAB releases that support the toolbox.

    Products — List of MathWorks® products required by your toolbox. Create this list manually.

    Examples, Apps, and Documentation

    Examples — Published MATLAB examples associated with your toolbox. To include .m and .mlx files as examples, click the Add examples button, select your code file, and click Publish HTML. MATLAB publishes the code to HTML and places the output files in the html folder.

    Alternatively, you can manually publish code files to HTML in MATLAB and then include the code files and the HTML files in your toolbox folder.

    • For a live script (.mlx) example, export it to HTML. On the Live Editor tab, select Save > Export to HTML and save it in a folder named html.

    • For a script (.m) example, publish it to HTML with the publish function. Do not specify an output folder when publishing your examples. For the Package a Toolbox tool to recognize the examples, the output folder must be the default folder (html).

    To create different categories for your examples, place the examples in different subfolders within your toolbox folder. When you add your toolbox folder to the Package a Toolbox dialog box, MATLAB creates a demos.xml file to describe your examples, and takes the example subfolder name as the example category name. Alternatively, you can create your own demos.xml file. The demos.xml file allows recipients to access your examples through the Supplemental Software section on the left side of the MathWorks documentation home page. For more information, see Display Custom Examples.

    Apps — Published MATLAB installable apps associated with your toolbox. The Package a Toolbox tool recognizes apps (.mlapp files) and app installer files (.mlappinstall files) and includes them in your toolbox.

    • To specify which apps (.mlapp files) are also installed and registered in the user's MATLAB Apps Gallery, select the apps.

    • All .mlappinstall files in your toolbox folder are installed and registered in the user's MATLAB Apps Gallery.

    Getting Started Guide — Quick start guide for your toolbox. For the Package a Toolbox tool to recognize a Getting Started Guide, include the guide as a live script named GettingStarted.mlx in a doc subfolder within your toolbox folder.

    Alternatively, you can generate and edit GettingStarted.mlx from the Package a Toolbox dialog box.

    Users of your toolbox can view the Getting Started Guide through the Options menu for the toolbox in the Add-On Manager. For more information, see Get and Manage Add-Ons.

    Help Browser Integration — Custom documentation for your toolbox to display within the MathWorks documentation. For the Package a Toolbox tool to recognize custom documentation, include an info.xml file to identify your documentation files. If you use the builddocsearchdb function to build the documentation database before packaging your toolbox, you can include the generated helpsearch subfolder in your toolbox. The info.xml file and the helpsearch folder allow recipients to access your documentation through the Supplemental Software link on the left side of the MathWorks documentation home page. For more information, see Display Custom Documentation.

    Alternatively, you can generate info.xml and helptoc.xml template files from the Package a Toolbox dialog box. To view your documentation within the MathWorks documentation, complete the documentation templates and include info.xml on the MATLAB path.

  5. Package your toolbox.

    • To save your toolbox, click Package at the top of the Package a Toolbox dialog box. Packaging your toolbox generates a .mltbx file in your current MATLAB folder.

    • To save your toolbox and share it on MATLAB Central File Exchange, select Package and Share from the Package menu at the top of the Package a Toolbox dialog box. This option generates a .mltbx file in your current MATLAB folder and opens a web page for your toolbox submission to File Exchange. MATLAB populates the File Exchange submission form with information about the toolbox. Review and submit the form to share your toolbox on File Exchange.

    When you create a toolbox, MATLAB generates a .prj file that contains information about the toolbox and saves it frequently. It is good practice to save this associated .prj file so that you can quickly create future revisions of your toolbox.

Share Toolbox

To share your toolbox with others, give them the .mltbx file. All files you added when you packaged the toolbox are included in the .mltbx file. When the end users install your toolbox, they do not need to be concerned with the MATLAB path or other installation details. The .mltbx file manages these details for end users.

For information on installing, uninstalling, and viewing information about toolboxes, see Get and Manage Add-Ons.

You can share your toolbox with others by attaching the .mltbx file to an email message, or using any other method you typically use to share files, such as uploading to MATLAB Central File Exchange. If you upload your toolbox to File Exchange, your users can download the toolbox from within MATLAB. For more information, see Get and Manage Add-Ons.

Alternatively, you can upload your toolbox to File Exchange when you package it. Select Package and Share from the Package menu at the top of the Package a Toolbox dialog box.

Note

While .mltbx files can contain any files you specify, MATLAB Central File Exchange places additional limitations on submissions. If your toolbox contains any of the following, it cannot be submitted to File Exchange:

  • MEX-files.

  • Other binary executable files, such as DLLs or ActiveX® controls. (Data and image files are typically acceptable.)

See Also

| | | | |

Related Topics