Temerity: Tutorials - Creating a Default Toolset

Tutorial: Creating a Default Toolset

Before you can do anything useful with Pipeline, you will need to create a default Toolset. A Toolset is essentially a named collection of environmental variables managed by Pipeline. Toolsets are used by Pipeline to determine the environment under which interactive programs are launched and batch programs are run in the queue. You construct a Toolset from a collection of Toolset Packages. Each Package is associated with a particular version of related programs and/or plugins which work together as a whole. Typically a Toolset Package is associated with a version of software package such as Maya, Houdini or RenderMan.

In order to create new Toolsets, you'll need to start plui(1) as the Pipeline Administor user (see --pipeline-user). This user has access to administrative operations not available to normal users. Once plui(1) is running, you'll need to open the Manage Toolset dialog from the main popup menu. This menu can be accessed by pressing (Alt+RightMouse) over the body of any panel or (RightMouse) over the panel menu button in the upper left corner of any panel.

The first Package you'll want to create should contain the base essentials required for all software at your site. This Package is typically called "Basic", but this name is arbitrary and can be name whatever you'd like. To create a new Package, press (Alt+RightMouse) over the right most area in the Manage Toolsets dialog titled "All Packages" and choose the New Unix Package item.

Once you has supplied the name for the Package and pressed the "Add" button, you will see this new Unix Package highlighted in the "All Packages" area. You can then start adding environmental variables using the Details item (same menu as New Unix Package) or simply by double-clicking on highlighted "working" item. The "working" label will eventually be replaced by a version number once you've frozen the Package.

To add an environmental variable, press the "Add Entry" and enter the name of the environmental variable. You can then edit its value in the dialog and set the method for combining this value with any values set by other Packages for the same variable. After adding a few variables, the Basic Unix Package might look like this:

The value on the right determines how values are combined when more than one Package defines the same environmental variable. Packages are combined in a specific order so that the following methods refer to combining the value of an environmental variable from the current Package with the value defined in a previous Package. The possible methods are:


Exclusive	The variable must not be defined in any previous package.
Override	The value will replace any existing value for the variable defined by a previous package.
Ignore	The value will be ignored if any previous package has already defined the variable.
AppendPath	The value is a colon separated path who's value is appended to the end of any previously defined path value for the variable.
PrependPath	The value is a colon separated path who's value is prepended to the beginning of any previously defined path value for the variable.

Once you have defined all of the environmental variables for a Package, you should test running the associated software under the environment defined by the Package. For the "Basic" Package, we could try running some common Unix programs like bash(1).

After you are satisfied that a Package works as expected, you can freeze the Package to create a permanent Package version.

You could now add Packages for other software packages. For example, here are Packages for the 6.5 and 7.0 versions of Maya.

You can then create Toolsets by combining these packages in a specific order. For example, say you wanted to create a Toolset for use on a particular production called "ProjectX". First you need to add a new Toolset using the New Unix Toolset menu item in the popup menu (Alt+RightMouse) for the "All Toolsets" area.

You can then create add Packages to this new Unix Toolset. When a Toolset is selected in the "All Toolsets" area, the "Included Unix Package" area displays the Packages assigned to the Toolset. At first, there are no Packages assigned. You can add the selected Package in the "All Packages" area to the "Included Unix Packages" by pressing the left arrow button on the divider between the two sections. Conversely, you can remove the selected package from the "Included Unix Packages" by pressing the right arrow button. Packages can be reordered by dragging them with the (MiddleMouse) button.

Go ahead and add all three packages to the "ProjectX" Toolset.

Notice the exclamation point next to the "Maya-7.0" Package and the "ProjectX" Toolset. This indicates that there is a conflict between environmental variables in the "Maya-7.0" Package and the packages previous included (above it). If you open the details dialog for the "Maya-7.0" package, you will see the offending variable "MAYA_LOCATION" is highlighted. Similarly, the details dialog for the "ProjectX" Toolset also highlights the problem variable.

Before a Toolset can be used in production, all conflicts like this must be resolved. In our somewhat contrived example, we can simply remove the "Maya-7.0" Package so that it no longer conflicts with "Maya-6.5". In more real world situations, conflicts usually signal that the Package has overstepped its bounds and is attempting to do something that would cause a failure for software associated with the other Packages. For instance, overwriting rather than appending to the PATH environmental variable.

Once you've settled on a combination of Packages which don't conflict, you should test running the software associated with these Packages to make sure they function properly. There is a "Test" menu item in the popup menu for the selected Toolset which opens the Test Package dialog for performing these tests. If you are satisfied that the Toolset works properly, you can use the "Freeze" item from the same popup menu to create a permanent version of the Toolset. Note that all of the Packages must be frozen before the Toolset which uses them can be frozen itself.

You can now add the newly frozen "ProjectX" Toolset active by selecting the Toolset and pressing the left arrow button between the "All Toolsets" and "Active Toolsets" areas. Active Toolsets are visible to artists can be be used to create new nodes or change the Toolset of existing nodes. Over time, the number of Toolsets can grow to include many obsolete Toolsets used on previous projects or for software rarely used. The Active Toolsets list allows administrators to keep the list of Toolsets exposed to artists down to a shorter and more relevant list. Note that even if a Toolset is no longer active, node versions may exist which use the Toolset. Being inactive does not prevent a Toolset from working properly, it only limits the choices of Toolsets available to artists when modifying the Toolset associated with a node.

The final step is to make the "Project X" toolset the Default Toolset. This is done using the "Default Toolset" menu item in the popup menu for the selected Toolset in the "Active Toolset" area.

Note that Toolsets completely determine the environment under which all software is run by Pipeline. This means that any user specific environment set before launching Pipeline is completely ignored. This is important in order to guarantee that nodes always function identically no matter what has happened to a user's environment since the node was last modified. On the other hand, it can sometimes be useful to set a user's environment outside of Pipeline to match a specific Toolset. Pipeline can generate a bash(1) shell script which when sourced will set the environment to match a given Toolset. You can use the "Export" menu item for the selected Toolset to write such a script to file.

Next Tutorial: Configuring Plugin Menus