Distributing files on Maya - Maya modules

How many of you struggle with installers and making Maya work with your content files which you may have to support multiple release, language, and platform? I know it is a hard work, and never easy... While working on a project for the next major Maya release, I had to make some research and chose on the technology to use for redistributing applications and contents for Maya. One nice feature in Maya is the support for ‘modules’ – see the API Guide topic here.

Modules are in fact a replicate of the Maya directory structure, where you put your application or content/asset files. That is a very nice approach to isolate ‘your’ files vs Maya files. So in case you apply a Maya hotfix or service pack, your application(s) will remain untouched, and that will also help you to maintain your files. Maya will work with your isolated files as if they were in the Maya directory structure.

The only thing you need to do is to create a text file (.txt or .mod) and put it somewhere in the Maya’ MAYA_MODULE_PATH search path. I would recommend to install the module file including the path of the plug-in into "[CommonFileFolder]Alias Shared\Modules\Maya\[<version_number>]" directory for Windows (/Users/Shared/Autodesk/maya/[<version_number>] for MacOS, and /usr/autodesk/modules/maya/[<version_number>-x64] for Linux), where is the version number of Maya which your plug-in supports. Maya uses the module file to locate and load the plug-in. But the is optional since you can specify that ‘condition’ in your module file itself. It is really your choice whether you want to distribute for 1 single version of Maya, or multiple.

The file can contain multiple ‘module’ definition and is very open to describe what it is.
A very simple syntax:

+ [Conditions] ModuleName ModuleVersion ModulePath

A relative path here is relative to the location of the module definition file itself.

Let’s ignore the optional conditions for now, and note that the only real important thing is the definition of the module’ path. In this Module Path, you will replicate the Maya directory structure, and put your files where Maya would expect to find them. For example put MEL scripts into the ‘scripts’ folder, xpm files into the ‘icon’ folder, etc…
The module name and version are important to be unique, so Maya can handle module smoothly and gives you information about modules loaded. See this 1 line definition example:

+ CyrilleModule 1.0.0.1 C:\Program Files\Cyrille Software\MyApp

Conditions is a way to tell Maya whether when a module should be loaded for a specific instance of Maya.
See this example:

+ PLATFORM:win32 CyrilleModule 1.0.0.1 C:\Users\Cyrille\MyApp
+ PLATFORM:win64 CyrilleModule 1.0.0.1 C:\Users\Cyrille\MyApp
+ PLATFORM:mac CyrilleModule 1.0.0.1 /Users/Cyrille/MyApp

Here using the same ‘directory’ structure, I do tell Maya to load my module from a specific location depending we’re running on a Mac or Windows. And since there is no definition for Linux, Maya will not load that module on a Linux Platform even if the files are installed on my Linux box. From there I would create a Maya like directory structure for my application (or content) regardless of my target architecture(s). You can create loading conditions based on PLATFORM (win32/win64/mac/linux), LOCALE (en_US/js_JP/zh_CN), and the Maya version MAYAVERSION.

There is one last thing important about modules which will make the use of modules the ultimate choice for redistributing applications/contents on Maya. A module definition file can also alterate System Variables at load time and with preprocessor symbols expansion. For example, you could write something like this:

+ CyrilleModule 1.0.0.1 C:\Users\Cyrille\MyApp
PATH+:=bin
PATH+=C:\Program Files\Autodesk\FBX\FBXConverter\2013.1\bin
MAYA_PLUG_IN_RESOURCE_PATH+:=resources/${FPPUILang}

and that would tell Maya to update the OS search path to add my module ‘bin’ folder to the PATH variable (relative to the module path, I.e. +:=) whereas the absolute path will jsut be added (I.e. +=) and to modify the MAYA_PLUG_IN_RESOURCE_PATH as well. Again these are controlled by the ‘Conditions’, so you get the real power to control how Maya should be setup to work with your module.

A relative path here is relative to the module location. Here the PATH ‘bin’ modification, becomes ‘C:\Users\Cyrille\MyApp\bin’. This is because of the relative notation using the character ':'

= is single variable assignment
+= is to append to an existing variable
:= is single variable assignment, but for a path relative to the module location
+:= is to append a path relative to the module location to an existing variable

However, this is not a perfect solution. There is 2 things modules won’t address automatically:

One common issue on any platform is the binary dependency search path. Modules won’t solve that issue for you, you will still need to make sure libraries/dll can be found by the OS as Maya will not solve that for you.
The second limitation is related to Mentalray Shaders. Shader definition files (those ending in .mi) must go into either Maya's own mentalray/include directory or one of the directories in the user's MI_CUSTOM_SHADER_PATH environment variable. Shader libraries (those ending in .so or .dll) must go into Maya's own mentalray/lib directory, or one of the directories in the user's MI_CUSTOM_SHADER_PATH environment variable, or one of the directories in the user's MI_LIBRARY_PATH environment variable.

Note that on both limitations there is a ‘module’ approach solution, but you will need to had some definition yourself as explained above with the system variable modification syntax.

Another issue is that it is very common to use a userSetup.mel (.py) script to do some initialization, but Maya will load only one userSetup.mel, and the first one found in its script search path. That means any setup scripts in modules might be ignored by Maya if the user defines its own setup script, or if another module is first in the search order and have a userSetup.mel file present. Something to remember... a workaround is to use the module '/scripts/startup' folder and have your initialization code posted there, or use a userSetup.py file instead. There is other workarounds, but too complicated compare to this one.

Based on this, if you need to write an installer for the 3 platforms, it becomes as easy as unzipping a file on the system and copy a .mod file.