Skip to content

Working with Toolboxes and Projects

Jump to bottom
Ben Heasly edited this page Jan 5, 2017 · 2 revisions

ToolboxToolbox supports two kinds of configuration: "toolboxes", which are shared with the world via the ToolboxRegistry, and "projects", which are intended for smaller groups but which still take advantage of ToolboxToolbox for dependency management and deployment.

This page is about the differences between toolboxes and projects, and how ToolboxToolbox aims to support them.

Toolboxes

Originally, ToolboxToolbox was focused on deploying shared toolboxes. These are usually:

Working with Toolboxes

ToolboxToolbox aims to make it a one-liner to deploy shared toolboxes in Matlab.

For example, this line will obtain or update a sample repository and add it to the Matlab path.

tbUse('sample-repo')

This slightly more practical example will deploy the sample repository along with the very handy jsonlab toolbox. It will also reset the Matlab path to an absolute state, to make sure that there are no lurking path conflicts/shadows/etc..

tbUse({'sample-repo', 'jsonlab'}, 'reset', 'full')

It's also possible to create and deploy custom configurations. This take more than one line, but offers more control. This example will deploy an alternate version of the sample repository, and get jsonlab from the Matlab Centreal File Exchange, instead of GitHub.

sampleRepo = tbToolboxRecord('name', 'sample-repo', 'flavor', 'v0.1', 'type', 'git', 'url', 'https://github.com/ToolboxHub/sample-repo.git');
jsonlab = tbToolboxRecord('name', 'jsonlab-mcfe', 'type', 'webget', 'url', 'https://www.mathworks.com/matlabcentral/mlc-downloads/downloads/submissions/33381/versions/22/download/zip');
tbDeployToolboxes('config', [sampleRepo jsonlab]);

Projects

ToolboxToolbox also supports "projects", which are not "toolboxes" in the sense of being reusable components, but which still want to use ToolboxToolbox for dependency management and deployment.

In contrast with toolboxes, projects may be:

  • frequently revised, refactored, or works in progress
  • expected to be used by small groups who are "in the know"
  • not expected to be re-used within larger works
  • deployed to a root projects folder which is separate from the usual toolboxes folder.
  • not known to the ToolboxRegistry
  • obtained by hand using tools like Git, and then deployed in Matlab using tbUseProject()

Working with Projects

Here is a recommended workflow for projects. This example will refer to a made-up project named "Foo".

When installing ToolboxToolbox, configure the root projects folder. This will be a top-level folder inside which ToolboxToolbox will search for projects by name.

Create a new project Foo or obtain an existing project repository for Foo. Place it in a folder named "Foo", anywhere inside the configured projects folder.

The project must contain a configuration file named Foo.json which contains the toolbox configuration for the Foo project. This configuration would be a JSON file much like the configuration files in the ToolboxRegistry. It must declare toolbox records for:

  • the project Foo itself, with name equal to "Foo", so that Foo can be configured and/or updated during deployments
  • toolbox dependencies for Foo, so that these can be deployed along with Foo

To deploy the project Foo, execute tbUseProject('Foo'). This will cause ToolboxToolbox to search for Foo.json and its containing folder Foo. When found, it will execute a deployment based on Foo.json.

Since Foo itself was already created or obtained by hand, ToolboxToolbox will not attempt to obtain Foo. But it will attempt to update Foo. It will also obtain or update dependencies of Foo. It will treat the dependencies as normal toolboxes, deployed into the normal toolboxes folder.

In summary, the workflow for projects is similar to the workflow for toolboxes. Except:

  • Initially, the use must create or obtain the project by hand, and place it inside the projects folder.
  • The project's configuration JSON would be located with the project itself, not in the ToolboxRegistry.
  • The user would deploy with tbUseProject('Foo') instead of tbUse('Foo').
Clone this wiki locally