Doing away with Houdini.env

This is a sort of sequel to the previous post I made about handling the Houdini.env file, and about configuring environments in general. Houdini 17.5 introduced the concept of “packages”, which are little JSON files (JSON meaning JavaScript Object Notation, filling a similar role as XML or YAML) that define Houdini-specific changes to be made to the environment. They’re meant to fill the exact same role as the Houdini.env file. JSON syntax can take a little getting used to, but the advantage of using packages over the Houdini.env file is that these packages can be easily enabled or disabled individually, and they can support special syntax for loading packages only when certain conditions are met (such as a specific build of Houdini).

SideFX has a reasonably long documentation page on what packages are and how they work, but I still keep seeing a lot of badly-configured package files floating around out there that can prevent your environment from working correctly when multiple packages are combined. Part of this is due to the internal inconsistency of how different “keys” in the package file are handled; for some reason, SideFX decided that any additions to the HOUDINI_PATH variable can be done with a special key called “path” that automatically operates in “prepend” mode, meaning each package automatically adds the new value to the beginning of HOUDINI_PATH. However, other environment-related keys default to the “replace” mode, and confusingly one of the common environment variables you need to edit is named “PATH”, and this is not the same as the special “path” key. Little inconsistencies like this can really throw a wrench in what should otherwise be a pretty simple file format. I’m going to explain a bit about how this syntax is supposed to work, and then write a couple of sample packages you can follow that should be enough to configure just about any add-on or plugin you choose to add to Houdini.

Important update: SideFX has deprecated the “path” key in packages in favor of “hpath”. The syntax is otherwise exactly the same. Moving forward past Houdini 20.0, you will want to start using “hpath” anywhere you see “path” (except for the “PATH” keys you see in the “env”!)

Package Syntax

Houdini package files are written in JSON, which is a bit finicky to say the least. If you’re not used to dealing with JSON, it’s basically a bunch of key/value pairs in a hierarchical structure. Each “object” in this structure is surrounded by curly braces ({ }). The file itself is one of these, so you’re going to have a pair of curly braces opening and closing the file as a whole. Any environment variables you want to store are another object, named env. This object internally is a list of environment variables you want to adjust, so it’s going to be surrounded by square braces ([ ]). So, before we’re adding any variables to our environment at all, here’s what a blank package would look like:

{
    "env": [
        {
        
        }
    ]
}

That’s looking pretty… useless. But now we can start filling in the blanks. You can see that I put another pair of curly braces in there, inside the square braces that define the list of environment variables we’re going to add. This is because each environment variable addition we make is another object, each with its own properties. Let’s start with the most obvious property here… what environment variable are we setting?

{
    "env": [
        {
            "PATH": "C:/ProgramData/Redshift/bin"
        }
    ]
}

The actual key/value pairs are just strings, separated by a colon. This is setting the PATH environment variable to be the given path on disk. It’s the equivalent of writing this in Houdini.env:

PATH="C:/ProgramData/Redshift/bin"

Those of you who have already slogged through a Houdini.env might notice that something’s missing, though… you usually want to append or prepend to the PATH variable, not replace it entirely. In Houdini.env, you typically do this by saying PATH=$PATH;"C:/ProgramData/Redshift/bin", and then writing this line over and over again for any other plugins you might be adding to your system path. With packages, you do this via the method property of this JSON object:

{
    "env": [
        {
            "PATH": "C:/ProgramData/Redshift/bin",
            "method": "append"
        }
    ]
}

Note that there’s a comma there after the PATH definition… JSON is very particular about this! You need a comma in between multiple objects in the same hierarchy. Setting the method to append here ensures that our new key is just going to be added to what’s already there.

Houdini gotchas

Of course, because it’s Houdini, it can’t be that easy. There’s a specially-named key in Houdini package files that you’ll frequenty see called path. This has nothing to do with the PATH environment variable set above… it’s actually a shortcut for HOUDINI_PATH. Worse still, it automatically assumes that you’re using the prepend method, whereas the env key assumes you are using the replace method. This trips up a lot of people when they’re trying to do anything more complex in a package than adding something to HOUDINI_PATH. You might even see this in some widely-distributed packages out there on the internet. If things start to fail when you’re combining multiple packages together, it’s worth taking a look in there and seeing if they’re following the right syntax!

Following our previous example for configuring a Redshift package, we still need to add the Redshift plugin path to HOUDINI_PATH to complete the install. Using the special path key, our package will look like this:

{
    "env": [
        {
            "PATH": "C:/ProgramData/Redshift/bin",
            "method": "append"
        }
    ],
    "path": "C:/ProgramData/Redshift/Plugins/Houdini/18.0.391"
}

Notice that extra comma after the closing square bracket! Now that we’re defining multiple keys inside the outermost object, we need a comma in between them.

The last main gotcha here is that you can’t have these things defined in Houdini.env and in a package file at the same time… it’s one or the other. My recommendation is to hose out your Houdini.env file entirely and replace all the keys you’re setting with packages. They’re so easy to individually swap in and out that you’ll have a much easier time adding, removing, or updating plugins and tools as necessary, even on a show-by-show basis.

Finishing up

The Houdini packages documentation goes into the specifics of where you can put these package files, but the usual directory is wherever your Houdini.env file typically goes on your system, plus /packages. So on Windows, you’d place all of these JSON files into C:/Users/butt/Documents/houdini18.0/packages. Each of these files will be processed in turn, and the result is the total environment for Houdini. Once you get used to the JSON syntax, it’s way easier than doing the old dance of semicolons and ampersands that we all had to do in Houdini.env.

The last thing I should mention is that packages are only a replacement for Houdini’s environment… they can never replace your system environment. I still recommend learning about how to manipulate environment keys on your given OS so that you can configure your projects in a more flexible manner… having auto-configured variables like $SHOW and $SHOT can save you a ton of time if done right, and the environment is a great place to tuck away “global” variables that you might need in multiple software packages all communicating with each other.

As a final example, here’s another package file that you could use to configure Arnold for Houdini. It’s almost exactly the same as Redshift… you can use this as a template for other tools you want to install, too! (Except MOPs. Use the included JSON for that one.) Just replace /path/to/htoa with the install location on your machine:

{
    "env": [
        {
            "PATH": "C:/path/to/htoa/htoa-5.0.2_raba8949_houdini-18.0.348/scripts/bin",
            "method": "append"
        }
    ],
    "path": "C:/path/to/htoa/htoa-5.0.2_raba8949_houdini-18.0.348"
}

Happy packaging!