Default Environment Handlers

Tractor comes with a default set of environment handlers. The handlers are invoked when there is a match between the incoming envkey and the keys definition in the environment key dictionary. The envkey parameter in a tractor script can actually be a list of several envkey entries. In that case each handler will be called in sequence to modify the launch environment.

Each of the default handlers has a specific purpose.

• SiteModulesPath

  default - The handler default is run on every command. It is run first, and the environment key dictionary should be setup with an intended default environment, rather than relying upon the environment of the launched blade.

  As provided the default handler simply sets the spooling host into the launch environment as REMOTEHOST. Default environment variables and paths should be setup here.

• rmshandler - The rmshandler responds to an incoming key of format rms-*-maya-*. The * indicates a globbing will be applied. This handler matches incoming keys like: rms-3.0.0-maya-2011.

  This handler extracts the RMS version, and the MAYA version and sets a number of environment variables including RMSTREE, MAYA_LOCATION, MAYA_MODULE_PATH. It also adds RMSTREE/bin and MAYA_LOCATION/bin into the path. These locations are determined by knowing the default install locations for these products on the specific platform. The handler will attempt to verify that RMS and Maya are installed before setting these variables.

• mayahandler - The mayahandler responds to an incoming key of format maya*. The * indicates a globbing will be applied. This handler matches incoming keys like: maya2011.

  The mayahandler provides similar functionality to the rmshandler, but is designed for Maya users who do not have RMS installed, but do Maya batch rendering. This handler extracts MAYA version and sets a number of environment variables including MAYA_LOCATION, MAYA_MODULE_PATH. It also adds MAYA_LOCATION/bin into the path. The Maya location is determined by knowing the default install location for Maya on the specific platform. The handler will attempt to verify Maya is installed before setting these variables.

• rmanhandler - The rmanhandler responds to an incoming key of format prman-*. This key is used to define the version of prman to be used, and is quite often used in conjunction with the rmshandler key above.

  This handler would match an incoming key like: prman-15.2. On a match the handler sets the environment variable RMANTREE, and adds RMANTREE/bin into the path. The location of RMANTREE is determined by knowing the default install location on the specific platform. The handler will actually attempt to determine whether the prman version is installed before setting the RMANTREE environment variable.

• rmantreehandler - The rmantreehandler is a special handler, which will generally not be used by customers. This handler responds to a key of format: rmantree=*. This handler is designed to work like the rmanhandler above, however, the key provides the entire path to a non-standard RMANTREE installation. For example, the incoming key might look like:rmantree=/opt/software/pixar/RenderManProServer-15.2. The entire path as defined in the key is set as the RMANTREE variable, and RMANTREE/bin is added into the path.

• rmstreehandler - The rmstreehandler is similar to the rmantreehandler above, however it is designed to point to a non-standard RMSTREE location. The handler responds to an incoming key of format: rmstree=*. A typical usage might bermstree=/opt/software/pixar/RenderManStudio-3.0.0-Maya-2011. This handler sets the RMSTREE environment variable, and adds RMSTREE/bin into the path.

The default handler source code is available and is located in the TrEnvHandlers.py file located in the blade-modules directory of the blade installation.

Adding A Custom Environment Handler

• Pick a name for your handler - it should be vaguely descriptive of the type of EnvKeys it handles. For the examples below, let's assume there is an inbound EnvKey called "ProjectX" and so we will call our handler "projxhandler".

• Pick a directory to hold your Python modules - typically this will be a location on a central fileserver that is accessible to all blade host. This location will be specified by SiteModulesPath.

• Add the selected directory to SiteModulesPath in blade.config - if all hosts mount the shared location using the same path, then it can go in the ProfileDefaults section, otherwise add customized variants to each profile as needed (shown below).

• Also add an EnvKeys entry for your new key - leave the key named "default" in the dictionary as well. Then add your module name as the envhandler value.

  {
      "ProfileDefaults":
      {   "ProfileName": "default",
          ...
          "SiteModulesPath": "/net/yourserver/tractor_extensions",
          "EnvKeys": [
              {
                  "keys": ["default"],
                  "environment": {
                      "SOME_VAR": "xyzzy",
                      "CURRENT_SHOW": "(not_set)"
                  },
                  "envhandler": "default"
              },
              {
                  "keys: ["ProjectX", "SHOT=*", "SCENE=*"],
                  "environment": {
                      "CURRENT_SHOW": "Project X, Venture of Mystery",
                      "CURRENT_SHOT": "$SHOT",
                      "CURRENT_SCENE": "$SCENE",
                      "RMANTREE": "/opt/pixar/RenderManProServer-15.2",
                      "PATH": "$RMANTREE:/bin;$PATH"
                  },
                  "envhandler": "projxhandler"
              },
          ]
      },
  
      "BladeProfiles":
      [...]
  }
  

• Also see the discussion on creating custom environment handlers