Tool Versioning

THIS DOCUMENT IS IN PROGRESS AND IS NOT SUPPORTED BY THE SHELL. FOR THE TIME BEING, USE REVISION CONTROL OUTSIDE OF HELGA TO VERSION YOUR SCRIPTS.

Tool Versioning is directly related to the Helga File Structure. Please read that document before this one.

Why We Need To Version Tools

As the needs of a production team change, so do their production support tools, often many times over the course of a single project. It becomes necessary to maintain and use both older and newer versions of the same tool. You need to be able to maintain older versions of tools so you can continue to use them even as new changes allow you to do new work.

A version control system partially solves this problem by enabling you to store revisions to tools and access older revisions of them. However, maintaining multiple versions on disk at the same time can quickly become cumbersome, and knowing which assets should use which versions of those files can be a tricky endeavor, especially for non-technical crew members.

Helga solves this problem by acting as a layer over the Subversion version control system. It manages multiple versions of files on disk and allows assets to define certain versions of tools to use.

How Helga Handles Versioning

Any executable file can be added to Helga as a "script" asset.

The script asset type derives from "file", and like file stores the path of a file on disk in the attribute "filePath". In this case it is the file to be executed.

Unlike most file assets, a script asset's file path is not hardcoded to a single file. It is instead a chunk of Helga code to be executed at runtime to resolve the real path to the file.

In this way, a single asset is made to point to potentially many files. This feature is not specific to scripts! It is a general feature of the Helga attribute system; any attribute can be set instead to a chunk of Helga code that will be evaluated any time the attribute's value is requested.

The format of script paths is:

SCRIPTROOT/VERSION/SCRIPTBASE

Scripts can be specified as site-wide or project-wide. This will be reflected in their location within the Helga asset structure, either under /scripts or /<project>/scripts. Scripts are versioned together at the site or project level; a "version" of your scripts reflects a specific state of all scripts in that scope.

Your site asset (/) and project assets should define the scriptRoot attribute (to be used as SCRIPTROOT in the path above). According to the Helga file structure, these should be located on disk underneath HELGAROOT/site. Usually, they are HELGAROOT/site/global for the site and HELGAROOT/site/<project name> for projects.

One of the factors used to resolve the variable filePath attribute into an actual path is the version given at runtime. Unless explicitly specified by the user, a default version of the script will be chosen based on the target asset's (e.g. the shot to be rendered) preferred global or project tool version. These preferred version numbers are stored in the attributes globalVer and <project>Ver (e.g. project1Ver). Like all attributes, these values are inherited, so one only needs to set globalVer on / and <project>Ver on /<project> to set defaults for the entire site and project. Assets that need to override this may, but otherwise don't need to define the attributes themselves.

Adding a Script

For a full example of adding and using a script, see Scripting for Helga. We will only cover here the information that pertains to tool versioning.

As stated above, script assets have variable paths that can be resolves to multiple files on disk. However, we don't want users to have to figure out the Helga code for a script in order to add it. So, we'll work backwards; the user provides an actual path, and we'll parse it into Helga code ourselves.

First the scope of the script must be determined. This is done by looking at its asset name. If it is located under /scripts, it's a global script. If it's located underneath any project asset (usually under /<project>/scripts) it is a project-wide script.

Next, the given path of the script must match its appropriate scriptRoot, as described above.

The new script will have an initial version number of the current version number of the appropriate scope at the time of adding.

The user-given path will be parsed into Helga code for storage into the new script's filePath attribute. For example, a user-given path might look like this:

/helga/site/global/trunk/render.tclsh

It will be parsed to look something like this:

[hget attr scriptRoot -name /]/[hget attr globalVer -name /]/render.tclsh

You may notice this implies a version number (hget attr globalVer...). This is only for display purposes. When the filePath is actually used, the correct version number will be swapped in by whatever mechanism is making use of the script.

Using a Script

Despite all of these complicated goings-on with versioning, Helga aims to provide as easy to use of an interface for script use as possible. Even via the Shell, this functionality is available opaquely through the hexec command.

hexec supports the -version argument, which the user may use to override any default version. Otherwise, the version will be determined through use of the globalVer/<project>Ver as described above, with a command like:

hget attr globalVer -name <target asset name>

The determined version, combined with the filePath of the script, will provide a real file path on disk to execute.

hexec (or more likely, some separate helper proc called by hexec) will handle making sure the file exists. If it doesn't exist, Helga will try to do an svn export to make that version of the file. If Helga can't do that, either because the export fails or the version specified simply does not exist, hexec will fail.

Adding a New Version of a Script

When you do an svn commit on a script, a new version is automatically created in Helga. This is accomplished through the use of an svn hook. This creates a version with a name of the format "r#", where # is the svn revision number. The files for this branch will not be created on disk until some tool of that version is requested for use.

Optionally, you can redo hadd script. Most of the arguments to hadd script - like -fullName or -desc will be updated for the existing asset. The -version argument may be given - if given, it will be used as the name of the new version. If this is in the "r#" format, an svn commit will be done if necessary and nothing special will be done. If in any other format, an svn commit will still be done if needed, and an svn tag will be created, tagging the revision with a custom text name. In this way a user can create more descriptive tags such as "release" or "dev". The file path given to hadd script should be under scriptRoot/<version given>/<script base name>. If a different path is given, Helga will try to copy the file from the location given, choosing to fail rather than overwrite a file already at the correct location.