On this page |
|
Overview
Traditionally, the way to set the values of environment variables in Houdini was to edit the houdini.env
file. The most important variable to set up is the $HOUDINI_PATH
, which tells Houdini where to look for files such as assets. You can also create convenience variables (for example $TEXTURE_DIR
) and edit system variables (such as the binary search path $PATH
).
The problem is that not only the user wants to set environment variables, but also studios, plug-in authors, and so on. Multiple parties would end up rewriting or appending to the houdini.env
file, sometimes causing errors or redundancy.
Also, you might want variables defined some times and not others (for example, switching between project-specific paths, or turning "experimental" assets on and off).
The new solution for this kind of set-up is packages. Packages are .json
files in HOUDINI_PATH/packages
. Each package file contains a specification for how to modify the environment (including the Houdini Path and other variables).
You can then have separate packages for:
-
Studio variables.
-
Project variables.
-
User variables.
-
Variables for each separate plug-in, tool, or add-on.
The file format supports a small expression language to allow some automation. With expressions you can, for example:
-
Enable/disable a tool installation or specify what package(s) are required by a tool.
-
Write generic package files.
-
Write a single package to manage a multi-platform setup.
-
Set variables conditionally with simple operators, Houdini keywords and environment variables.
This removes the need to edit houdini.env
.
Using package files
-
Package files must be valid JSON and must have the
.json
extension. -
Houdini will scan the following directories on startup (if they exist) for package files:
-
$HOUDINI_USER_PREF_DIR/packages
-
$HFS/packages
-
$HSITE/houdinimajor.minor/packages
(for example,$HSITE/houdini18.0/packages
) -
$HOUDINI_PACKAGE_DIR
Houdini will process the package files directly in the folders specified in
HOUDINI_PACKAGE_DIR
, do not add apackages
directory under these folders.$HSITE
must be set to an existing directory before starting Houdini.
-
-
Houdini process files it finds first in the directory order above, then within each directory alphabetically by file name.
-
You can have multiple package files in each
packages
directory on the above path. -
Houdini does not scan subdirectories inside
packages
. -
Extra package folders can be specified dynamically from a package file.
Writing the package file
The following keywords are used for writing a package:
env
Sets or modifies environment variables.
enable
Enables or disables a package.
load_package_once
Prevents a package from being loaded multiple times. Houdini will load the first package in the search path with "load_package_once": true
, and ignore any other packages with the same file name in the search path. This keyword defaults to false
.
package_path
Scans package paths dynamically.
path
Shortcut to set HOUDINI_PATH
.
recommends
Checks specific package(s) availability without enforcing a dependency.
requires
Checks specific package(s) availability and enforces a dependency.
Manipulating the Houdini Path
To... | Do this |
---|---|
Prepend a new directory to the Houdini Path |
{ "path" : "/user/bob/libs" } The |
Prepend multiple directories to the Houdini Path |
{ "path" : [ "/user/bob/libs", "/user/tom/libs", "/user/sam/libs" ] } |
Edit the value of a variable using the |
New path elements are prepended by default. In places where you would use a string value to prepend to the path, you can replace it with a JSON object containing a The value for To append one element and prepend two others to the Houdini Path: { "path" : [ { "value" : "/user/bob/libs", "method" : "append" }, "/user/tom/libs", "/user/sam/libs" ] } To overwrite the previous Houdini Path with a new path: { "path" : [ { "value" : [ "/user/bob/libs", "/user/tom/libs", "/user/sam/libs" ], "method" : "replace" } ] } |
Specify that the package file depends on another package file. |
If you use a { "recommends" : "package_name", "path" : "/user/bob/libs" } If you use { "requires" : ["package1","package2"], "path" : "/user/bob/libs" } The value of either key can be a package name string or an array of package name strings. |
Add or don’t add a path element based on an expression |
In places where you would use a string value, you can replace it with a JSON object where instead of { "path" : [ {"houdini_os != 'windows'" : "/user/bob/libs"}, {"houdini_os == 'windows'" : "$HOME/bob_win_libs"}, {"$use_tom_libs == '1'" : "$HOME/tom_libs"} ] } See package expressions below. |
Mark a package as "not enabled" so Houdini ignores it |
The { "enable" : false, "path" : "/user/bob/libs" } Instead of a boolean, the value of the { "enable": "houdini_os == 'linux'" } If you want to reverse the meaning of the expression, you can make it generate the value { "enable": { "houdini_os == 'linux'": false } } |
Prevent Houdini from loading the other packages with the same package file name found later in the search path |
Use the { "load_package_once" : false } Or the value of { "load_package_once": "houdini_os == 'linux'" } Or JSON Map: { "load_package_once": { "houdini_os == 'linux'": false } } |
Set arbitrary environment variables
To... | Do this |
---|---|
Set/modify an environment variable |
The top-level keyword
Note The The following set { "requires" : ["package1","package2"], "env": [ { "BOB": "$HOME/bob_tool" }, { "HOUDINI_PATH" : [ "$BOB/libs", { "houdini_version>'17.5' and houdini_version<'17.5.250'": "$BOB/test", "method": "append" } ] } ] } You can also use an alternate syntax for defining environment variables using the reserved keys { "requires" : ["package1","package2"], "env": [ { "var": "BOB", "value": "$HOME/bob_tool" }, { "var": "HOUDINI_PATH", "value": [ "$BOB/libs", { "houdini_version>'17.5' and houdini_version<'17.5.250'": "$BOB/test2", "method": "append" } ] } ] } You can define custom path variables. { "env": [ { "MYPATH": ["$HOME/bob_tool", "$HOME/bob/test"] } ] } Use curly braces ({}) to concatenate a variable value and a value literal. The curly brace syntax is the same as the HSCRIPT variables syntax. { "env": [ {"BOB": "/home/bob/bob_tool"}, {"BOB1": "${BOB}1"}, {"BOB2": "${BOB}2"} ] } From Hscript Textport: / -> echo $BOB /home/bob/bob_tool / -> echo $BOB1 /home/bob/bob_tool1 / -> echo $BOB2 /home/bob/bob_tool2 Use this format Some examples defined in { "path" : [ "${EMPTY_VAR-/var/tmp}", "${BOB_TOOL-${HOUDINI_PACKAGE_PATH}/../BOB_TOOL}" ], "env": [ {"BOB": "${BOB_TOOL-/home/bob/bob_tool}"}, {"BOB1": "${BOB_TOOL_V1-${BOB}}"} ] } The variables set in . echo $HOUDINI_PATH /var/tmp:/home/bob/packages/../BOB_TOOL . echo $BOB /home/bob/bob_tool . echo $BOB1 /home/bob/bob_tool |
Relative path variables
To... | Do this |
---|---|
Set environment variable relative to the package |
The For instance, given this package file { "env": [ { "HOUDINI_PATH": "$HOUDINI_PACKAGE_PATH/../tools" } ] } Houdini will resolve HOUDINI_PATH := '/home/user/bob/packages/../tools;&'
|
Set package folders dynamically
In addition to the startup folders that you specify upfront for loading package files, Houdini lets you set extra package folders from a package file:
-
Use the
package_path
keyword for setting either a single folder or an array of folders. -
Houdini will process the package files located directly in the specified folders, do not add a
packages
directory under these folders. -
Houdini will queue the extra package folders and will process them recursively. The queue is processed when the current package folders have been processed. The loop ends until there are no more folders added to the queue.
Note
Environment variables set with the env
keyword cannot be used for setting package_path
. You can only use variables from the environment where Houdini was launched.
To... | Do this |
---|---|
Set a single folder to scan |
{ "package_path" : "$HOME/bob_tool" } |
Conditionally specify a folder |
{ "package_path" : { "houdini_version == '18.0.302'": "/opt/bob/packages" } } |
Set an array of folders to scan |
{ "package_path" : [ "$HOME/bob_tool", "/opt/tom_tool" ] } |
Set an array of folders |
{ "package_path": [ "$HOME/bob_tool1", "$HOUDINI_PACKAGE_PATH/../bob_tool2", {"houdini_version > '17'" : "$HOME/bob_tool3" } ] } |
Examples
Path
Prepend a path to |
{ "path": "$HOME/bob_tool/libs" } |
Add multiple paths |
{ "path": ["$HOME/bob_tool/libs", "$HOME/bob_tool/test"] } |
With expression |
{ "path": {"houdini_os == 'windows'": "$HOME/bob_tool/libs"} } |
Env
Define multiple environment variables |
{ "env" : [ { "BOB" : "$HOME/bob_tool" }, { "TOM" : "$HOME/tom_tool" } ] } |
Use expressions |
{ "env": [ { "QUAD_LIBS": { "houdini_version > '17.0' and houdini_version < '17.5'" : "$HOME/quad_libs" } } ] } |
Use expressions with environment variables |
{ "env": [ { "SERVER1": { " $MY_SERVER_SETUP == 'ICARUS' ": "/servers/icarus" } }, { "SERVER2": { " $MY_SERVER_SETUP == 'MERCURY' ": "/servers/mercury" } } ] } |
Create and reuse variables |
{ "env" : [ { "BOB" : "$HOME/bob_tool" }, { "BOB_TEST" : "$BOB/test" } ] } |
Prepend path to |
{ "env" : [ { "HOUDINI_PATH" : "$HOME/bob_tool" } ] } |
Append path to |
{ "env" : [ { "HOUDINI_PATH" : { "value": "$HOME/bob_tool", "method": "append" } } ] } |
Replace |
{ "env" : [ { "HOUDINI_PATH" : { "value": [ "$HOME/bob_tool", "$HOME/tom_tool" ], "method": "replace" } } ] } |
Multiple variables |
{ "env": [ { "BOB" : "$HOME/bob_tool" }, { "HOUDINI_PATH" : { "value": [ "$BOB/libs", { "houdini_version>'17.5' and houdini_version<'17.5.250'": "$BOB/test", "method": "append" } ] } } ] } |
Modify system |
{ "env" : [ { "PATH" : { "value": [ "$HOME/bob_tool", { "value": "$HOME/tom_tool", "method": "append" } ] } } ] } |
Recommends/requires
Display warning if bob_tool package is missing |
{ "recommends": "bob_tool" } |
Multiple dependencies |
{ "recommends": [ "bob_tool", "tom_tool" ] } |
Conditional dependency |
{ "recommends": { "houdini_version > '17.0'": "sam_tool" } } |
Display error if bob_tool package is missing |
{ "requires": "bob_tool" } |
Multiple requirements |
{ "requires": [ "bob_tool", "tom_tool" ] } |
Conditional requirement |
{ "requires": { "houdini_version > '17.0'": "sam_tool" } } |
Package Expressions
Expressions can be used for setting package variables conditionally. The grammar supports boolean expressions defined with the following set of comparison and logical operators.
-
The expression can use the following operators:
(
,)
,==
,!=
,<
,>
,<=
,>=
,and
,or
. -
You can establish precedence using brackets
()
. Otherwiseand
andor
have higher precedence, and the comparison operators all have the same lower precedence. -
You can compare with a literal string by enclosing the string in single quotes.
'This is a valid string'
-
You can use environment variables in a comparison by prefixing the variable name with
$
.$MY_VAR == '/var/tmp' $HOME == '/user/bob'
-
You can use the following "keywords" as part of a comparison:
houdini_version
The current Houdini version (full version path).
houdini_os
The OS platform ('windows', 'linux', 'macos')
-
The expression language supports string values only. Other types may be supported in the future for new identifiers.
Examples
"houdini_version == '16.5'" "houdini_version == '16.5' and houdini_os=='linux'" "houdini_version => '16.5' and houdini_version < '17.5'" "houdini_os != 'windows' or houdini_version == '17.5' or houdini_version == '17.5.56'" "(houdini_os != 'macos') or (houdini_version >= '17.4' and houdini_version <= '17.5')" "houdini_os == 'windows' and houdini_version >= '17.5' and $USE_XYZ == 'TRUE'"
Packaging techniques
Here are a few common techiques for packaging plugins in Houdini.
Easy way to integrate plugin files
Create a package file to set the $HOUDINI_PATH
with the plugin folder to tell Houdini where to look for the plugin HDA
, python panel
and viewer state
files.
Plugin folder:
$HOUDINI_USER_PREF_DIR/xyzplugin18.5/ otls/ python_panels/ viewer_states/
Package file:
$HOUDINI_USER_PREF_DIR/packages/xyzplugin.json { "path": "$HOUDINI_USER_PREF_DIR/xyzplugin18.5" }
Plugin versionning
Multiple version support is possible by setting the $HOUDINI_PATH
based on the Houdini current version.
$HOUDINI_USER_PREF_DIR/packages/xyzplugin.json { "env": [ { "XYZ": [ { "houdini_version == '18.0'": "$HOUDINI_USER_PREF_DIR/xyzplugin18.0" }, { "houdini_version == '18.5'": "$HOUDINI_USER_PREF_DIR/xyzplugin18.5" } ] } ], "path": "$XYZ" }
Plugin versionning method 2
Another approach for plugin versionning is to use multiple package files. The package matching the current version of Houdini will be marked as enabled and processed:
$HOUDINI_USER_PREF_DIR/packages/xyzplugin18.5.json { "env": [ { "XYZ": "$HOUDINI_USER_PREF_DIR/xyzplugin18.5" } ], "path": "$XYZ", "enable": "houdini_version == '18.5'" }
$HOUDINI_USER_PREF_DIR/packages/xyzplugin18.0.json { "env": [ { "XYZ": "$HOUDINI_USER_PREF_DIR/xyzplugin18.0" } ], "path": "$XYZ", "enable": "houdini_version == '18.0'" }
Loading HDAs with OPlibraries
By default Houdini scans the folders in HOUDINI_OTLSCAN_PATH
to load HDA files. This is done if the
Operator Type Manager dialog is configured not to use OPlibraries
files to find HDA files. However, plugins must use a OPlibraries
file to ensure their HDA
files are loaded if the user choose to set the OPlibraries
option.
1) Put an OPlibraries
file in the package folder. The file must list all HDA files to load with a path relative to the plugin folder.
$HOUDINI_USER_PREF_DIR/xyzplugin18.5/OPlibraries otls/OPlibXYZ.hda
2) Tell Houdini where to find the OPlibraries
file. This is normally achieved by setting $HOUDINI_PATH
or HOUDINI_OPLIBRARIES_PATH with the plugin folder.
Tips
-
You can quickly display the contents and order of the Houdini Path in Houdini’s Python shell by calling hou.houdiniPath().
-
You can define an environment variable earlier in the
env
array and then use that variable in a value later in the array. Make sure the variables are defined before they are used. -
Environment variables set in one package can be referenced by other packages as well.
-
Environment variables set in packages only affect the Houdini process (for example, they do not affect the shell if you launch Houdini from a command line).