Deployment Snapshots

ToolboxToolbox can create snapshots of existing deployments. These are "version-pinned" configurations that record the current version of each toolbox. Snapshots should support deployments that need to be stable over time, for example when publishing results that used specific toolbox versions.

In addition to toolbox versions, a snapshot records extra information about the host system, such as the OS and Matlab versions. Although ToolboxToolbox can't actually deploy OS and Matlab versions, this information may be useful for reference.

Create a Snapshot

To create a snapshot configuration, you would deploy normally and keep track of the returned results.

results = tbUse('sample-repo');

This example deploys with tbUse(). Results returned from several functions should work just as well, including:

• tbUse()
• tbUseProject()
• tbDeployToolboxes()
• tbDeployToFolder()

Once you have results of a successful deployment, you can ask ToolboxToolbox to detect the version of each toolbox, and make a new configuration that fills in the version information.

snapshot = tbDeploymentSnapshot(results);

The snapshot contains a copy of the original configuration, with version information filled into the flavor field:

>> snapshot(1)

ans = 

                extra: ''
               flavor: 'c17d66bd1ea74d46e215cea3eb4032bbb4d32778'
                 hook: [1x0 char]
           importance: ''
    localHookTemplate: ''
                 name: 'sample-repo'
        pathPlacement: 'append'
      requirementHook: ''
            subfolder: [1x0 char]
          toolboxRoot: [1x0 char]
                 type: 'git'
               update: 'never'
                  url: 'https://github.com/ToolboxHub/sample-repo.git'

It also contains an extra record with general system information:

>> snapshot(2).extra

ans = 

     matlab_version: '9.0.0.341360 (R2016a)'
         matlab_ver: '--------------------------------------…'
               java: 'Java 1.7.0_75-b13 with Oracle Corporation Java HotSpot(TM) 64-Bit Server VM mixed mode'
           computer: 'MACI64'
    toolboxRegistry: [1x1 struct]
     toolboxToolbox: [1x1 struct]

Note that version information is only available for some toolbox types like git and svn, but not others like installed and webget.

Save a Snapshot

tbDeploymentSnapshot() returns a configuration struct array. Aside from having versions filled in, this is just like any other configuration. So you can save and load to and from JSON, like any other configuration.

For example:

tbWriteConfig(snapshot, 'configPath', 'my-snapshot.json');
snapshotAgain = tbReadConfig('configPath', 'my-snapshot.json');

Saving a snapshot to JSON should help with archiving, sharing, and publishing.

Deploy from a Snapshot

You can also deploy a snapshot like any other. For example:

results = tbDeployToolboxes('configPath', 'my-snapshot.json');

This will deploy the snapshot along side your other toolboxes. This might be what you want. Or, you might want to deploy a snapshot temporarily and then delete it. That way, the version-pinned toolboxes would not clutter up your normal toolbox folder or interfere with your normal local hooks.

You can deploy a snapshot to an alternative folder using tbDeployToFolder().

tempFolder = '~/my-temp-folder';
results = tbDeployToFolder(tempFolder, 'configPath', 'my-snapshot.json');

This would deploy every toolbox in the snapshot to the chosen tempFolder. When done with the snapshot, you could simply delete the tempFolder and go back to deploying your regular toolboxes.

Snapshots with Local Hooks

Some toolboxes use a local hook for setting up preferences, like local file paths. This can be a challenge for snapshots because local hooks are intended to live outside of code repositories, which makes them un-versioned and therefore not part of the snapshot itself.

So you might have local hooks that work well normally, with up-to-date toolboxes. But these hooks might be incompatible with older toolbox versions of the same toolbox deployed from a snapshot.

To deal with this, you can deploy snapshots using tbDeployToFolder(). This will create a separate local hooks folder, just for the snapshot deployment, and fill it with fresh local hooks based on the localHookTemplate declarations in the snapshot toolbox records. These fresh hooks will be based on the snapshot toolbox versions, and they will not interfere with the local hooks that you use normally.

See Local Hooks for more about local hooks, and writing local hook templates that can run without requiring customization.