Toolbox Records and Types

The ToolboxToolbox supports several types of toolbox like Git repositories, file downloads, local files, etc. Here is a description of each type.

Each description contains a short explanation of the toolbox type, and the toolbox record fields that are important for that type.

All Types

In general, you can declare toolbox records using the tbToolboxRecord() function. You can pass name-value pairs to the function to fill in record fields. For example:

>> record = tbToolboxRecord( ...
    'name', 'sample-repo', ...
    'type', 'git', ...
    'url', 'https://github.com/ToolboxHub/sample-repo.git')

record = 
                extra: ''
               flavor: ''
                 hook: ''
           importance: ''
    localHookTemplate: ''
                 name: 'sample-repo'
        pathPlacement: 'append'
 printLocalHookOutput: ''
      requirementHook: ''
            subfolder: ''
          toolboxRoot: ''
     toolboxSubfolder: ''
                 type: 'git'
               update: ''
                  url: 'https://github.com/ToolboxHub/sample-repo.git'

The following fields apply to all toolbox types.

Field	Default	Interpretation
name	''	Unique name for this toolbox.
type	''	What strategy to use for this toolbox, like git, webget, etc. See below.
importance	''	If 'optional', allows this toolbox to fail without failing the whole deployment.
update	''	If 'never', this toolbox will be obtained when missing but not automatically updated.
pathPlacement	'append'	If 'append', add to the bottom of the Matlab path. If 'prepend' add to the top. If 'none', don't add to the Matlab path at all. There are also 'appendrootonly' and 'prependrootonly' options. These behave as 'append' and 'prepend' in terms of path placement, but only put the top level folder on the path (i.e. they don't invoke a call to genpath() on the top level folder.) We have not explored how these latter two options interact with the specification of a subfolder; with luck they will only cause the top level of the specified subfolder(s) to be put on the path.
printLocalHookOutput	''	If set to '1', don't suppress output/warnings from local hook. If set to '0', then do so. Overrides toolbox default for this parameter, for the particular record.
subfolder	''	Optional folder or cell array of folders within the toolbox to be added to the Matlab path, instead of the whole toolbox.
toolboxRoot	''	Optional local path, where to put this toolbox instead of the usual toolbox folder. If this begins with #, first the code looks for the toolbox under the projects directory and uses that if it is found. Otherwise it is fetched and placed with the specified subfolder (the part after the sharp) of the projects directory. This feature is a bit of a kluge and might be brittle.
toolboxSubfolder	''	If the field is set in a toolbox json config file, the toolbox is stored in toolboxRoot/toolboxSubfolder.
hook	''	Matlab command to eval() after deploying this toolbox.
localHookTemplate	''	Path to script within the toolbox to copy to the user's local hook folder and run each time the toolbox is deployed.
requirementHook	''	Name of function that checks for system requirements that ToolboxToolbox can't deploy, such as native system libraries. Function must have signature [status, result, advice] = foo(). advice should be links and/or advice for obtaining the requirements if missing.
java	''	Name(s) of jar files to add to dynamic java class path. Names are specified relative to the toolbox.
extra	''	Any additional data to keep with this record but ignore during deployments -- ie comments.

git

Toolbox records with type 'git' use Git to obtain a toolbox (git clone) and keep it updated (git pull).

Field	Default	Interpretation
url	''	Url where the Git repository can be cloned. Can be a multi-OS url, see help text for routine tbProcessMultiOSUrl.
flavor	''	Optional Git branch, tag, or commit id to checkout after cloning, instead of master.

svn

Toolbox records with type 'svn' use Subversion to obtain a toolbox (svn checkout) and keep it updated (svn update).

Field	Default	Interpretation
url	''	Url where the Svn repository can be checked out. Can be a multi-OS url, see help text for routine tbProcessMultiOSUrl.
flavor	''	Optional Svn revision to check out and update.
subfolder	''	Optional subfolder to add to path, especially trunk, branches, etc..

webget

Toolbox records with type 'webget' use Matlab's websave() function to download a file from the web. If the file is a zip file, it will be expanded automatically.

This strategy contains some special case code to handle the particular URLs that are currently provided by Matlab Central. These do not include the zip filename at the end; the code detects that it is a Matlab central URL and handles this by a few special case string manipulations. This is probably a bit fragile, and subject to breaking next time Matlab changes the way they do things. If the code detects that it is a Matlab central URL, it also puts the folder inside a subfolder of the toolbox folder, called matlabcentral. The idea is to keep all the matlabcentral code easily identifiable on your machine. Probably this functionality should be implemented as a separate strategy, rather than as a special case of the webget strategy.

The behavior is the same when obtaining or updating this type of toolbox -- just (re)download it. To prevent extra downloads, use

tbToolboxRecord('update', 'never', ... )

Field	Default	Interpretation
url	''	Url where the file can be downloaded. Can be a multi-OS url, see help text for routine tbProcessMultiOSUrl.
flavor	''	If zip file will be unzipped, regardless of file extension.

local

Toolbox records with type 'local' point to folders on the local file system. These don't need to be obtained or updated, but they will be added to the Matlab path.

Field	Default	Interpretation
url	''	file:// Url or local file path where the toolbox is located. Can be a multi-OS url, see help text for routine tbProcessMultiOSUrl.

installed

Toolboxes with type 'installed' point to installed Matlab toolboxes, for example "Image Processing Toolbox" or "Parallel Computing Toolbox". These don't need to be obtained or updated, but they will be added to the Matlab path.

You can use the Toolbox toolbox to select which installed Matlab toolboxes you want to use. This is a nice way to communicate to others which Matlab toolboxes your code depends on.

To make your deployments predictable, you can remove all installed Matlab toolboxes from the path when you deploy a configuration. For example:

tbUse('sample-repo', 'reset', 'no-matlab');

Field	Default	Interpretation
name	''	Name of a Matlab installed toolbox folder, like 'images'. See toolboxdir().

docker

Toolbox records with type 'docker' point to Docker images on DockerHub. These can be obtained and updated but won't be added to the Matlab path.

Field	Default	Interpretation
url	''	DockerHub path for the image, like "ninjaben/archiva-docker" or "ubuntu". Can be a multi-OS url, see help text for routine tbProcessMultiOSUrl.
flavor	''	The tag of the image, like "latest" or "16.04".

include

Toolbox records with type 'include' point to other toolbox configuration JSON files. They are not themselves obtained, updated, or added to the Matlab path.

Instead, the indicated files will be loaded with tbReadConfig(), so that records stored in the JSON can be deployed. This allows toolbox configurations to build on each other without duplicating information.

Records may indicate JSON files using the url field. Alternatively, records my omit the url, in which case the ToolboxHub ToolboxRegistry will be searched for a configuration file based on the record's name field.

Note that 'include' records are intended for locating JSON files, which may in turn contain any number of toolbox records. The details of the included toolboxes, like their types and flavors, are left up to the JSON file.

Field	Default	Interpretation
name	''	Name used to search the ToolboxRegistry for JSON.
url	''	Optional Url or local file path where a JSON configuration file is located. Can be a multi-OS url, see help text for routine tbProcessMultiOSUrl.

Custom Class Name

You can extend the ToolboxToolbox to support additional types of toolbox by writing a subclass of the TbToolboxStrategy class. See Custom-Toolbox-Strategies.

To use your custom toolbox type, use the name of your class as the toolbox record type. For example:

tbToolboxRecord('type', 'MyCustomToolboxStrategy', ... )