All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Compiling HDK Code

Table of Contents

Compiling on Linux/OSX with hcustom

The easiest way to compile HDK sample code or your own custom HDK code is to use the hcustom command-line tool. In order to use hcustom, you need csh. On newer Linux platforms (i.e. Ubuntu), you need to install csh manually using your package manager since it is not shipped by default.

Once csh is installed, you can try compiling the SOP Star sample (see SOP/SOP_Star/SOP_Star.C) using hcustom. Open a command shell and run:

# Source the Houdini environment.
# On OSX, use Command Line Tools from Application menu
cd /opt/hfsX.Y.ZZZ
source houdini_setup
# Copy the toolkit samples to your working space.
# Make sure you have full permissions on the samples folder.
cd $HOME
cp -R $HFS/toolkit/samples .
chmod -R 777 ./samples
# Dive into the SOP samples directory.
# Build the SOP Star example.
cd ./samples/SOP/SOP_Star
hython $HHP/generate_proto.py SOP_Star.C SOP_Star.proto.h
hcustom SOP_Star.C

hcustom will produce a corresponding object file, SOP_Star.o, and a plugin library, SOP_Star.so, in the current working directory. The library file is automatically installed into $HOME/houdiniX.Y/dso as well. This is where Houdini is able to locate and load your custom plugins.

So if you open Houdini and create a Geometry object, you can dive into the geometry and press TAB->SOP Star and your Star surface operator will appear.

In order to run hcustom, you need to have the C-Shell (i.e. /bin/csh) installed on your system.

Compiling on Windows (MSVC) with hcustom

To compile HDK code on Windows using MSVC, open the Windows START menu and choose Side Effects Software -> Houdini X.Y.ZZZ -> Command-line Tools from your program list. This will launch a command shell with the Houdini environment initialized. hcustom will autodetect your Microsoft Visual C++ distribution. You can confirm that it's correct by running hcustom --output_msvcdir . To manually override this, set the MSVCDir environment variable to point to the Microsoft Visual C++ distribution. Note that this directory should have the subdirectories bin, include, and lib.

Here is an example:

cd /D %HFS%\toolkit
xcopy /S samples C:\samples
cd /D C:\samples\SOP\SOP_Star
hython %HHP%/generate_proto.py SOP_Star.C SOP_Star.proto.h
hcustom SOP_Star.C

Other than using hcustom, one can build using GNU Make or Visual Studio's nmake, see the Compiling with Makefiles section.

If you wish to build from the Visual Studio IDE, then it's suggested that you use CMake instead, see the Compiling with CMake section.

For other build systems, you need to use the same compiler settings as hcustom. To see what they are, you can run "hcustom --cflags" for the compiler options, and "hcustom --ldflags" for the linker options.

Compiling with Makefiles

Overview of Compiling with Makefiles

Though hcustom is convenient and easy-to-use, it is not suitable for compiling mid-size and large HDK projects. For one reason, hcustom can only compile a single C++ source file into a plugin library. If your HDK plugin is built from several source files, then it is recommended that the Makefiles from $HFS/toolkit/makefiles be used to manage your compilations.

There are two Makefiles to choose from depending on the make tool that you are using:

  • Makefile.gnu - For the GNU make tool
  • Makefile.nmake - For the Microsoft NMAKE tool

There are also OS-specific Makefiles (i.e. Makefile.osx, Makefile.linux, Makefile.win) which contain platform-specific definitions. These files are referenced by the Makefiles listed above and should never be used directly.

To compile your source files, first create a new Makefile. In your Makefile, you need to define a few variables to setup the compile and link targets. Here is a list of the variables that you can set:

Variable Name Description
APPNAME (required) The filename for your standalone application. If you are building a plugin library, then set DSONAME instead of APPNAME.
DSONAME (required) The filename for your plugin library. For the SOP Flatten example, this would be SOP_Flatten.so on Linux and SOP_Flatten.dll on Windows. If you are building a standalone application, then set APPNAME instead of DSONAME.
INCDIRS A space-separated list of additional include directories that are searched at compile-time. Each entry in the list should be in the form -I/path/to/include/dir.
ICONS Name of the icon files to install. This only applies if you are building a plugin with custom node operators.
INSTDIR Directory to install your standalone application or plugin library (and support files). If not specified, then this will default to $HOME/houdiniX.Y.
LIBDIRS A space-separated list of additional library directories that are searched at link-time. Each entry in the list should be in the form -L/path/to/lib/dir on Linux and -LIBPATH:C:/path/to/lib/dir on Windows.
LIBS A space-separated list of additional libraries to link to at link-time. For shared libraries, use -lmyLibrary on Linux and myLibrary.lib on Windows. For static libraries, use /path/to/lib/myLibrary.a on Linux and myLibrary.lib on Windows.
OPTIMIZER The optimization flag. If not specified, then OPTIMIZER is set to -O2 by default on Linux and -Ox on Windows.
SOURCES (required) A space-separated list of C++ source files that are to be compiled into the plugin library or application. The source files must have a .C extension.

After defining the compile and link variables, include one of Makefile.gnu or Makefile.nmake into your Makefile.

Once you have a Makefile created, you can invoke make with various targets.

# If target_name is omitted, then the "all" target is used.
make [target_name]
Target Name Description
all Default target that just builds and links the sources.
clean Removes files created by the all target.
install This invokes the all and icons targets, and then installs into the value specified by the INSTDIR variable.
icons Installs the icons specified by the ICONS variable.

Compiling a Simple Example with Makefiles

Below is a simple example Makefile that compiles the SOP_Flatten.C HDK sample.

# Makefile
# Usage: Place this in the same directory as SOP_Flatten.C, and then from that
# directory run: make install
DSONAME = SOP_Flatten.so # Use SOP_Flatten.dll for Microsoft Windows
# For GNU make, use this line:
# include $(HFS)/toolkit/makefiles/Makefile.gnu
# For Microsoft Visual Studio's nmake use this line instead
# !INCLUDE $(HFS)/toolkit/makefiles/Makefile.nmake
include $(HFS)/toolkit/makefiles/Makefile.gnu

Compiling a Library with Makefiles

Below is an example of a custom Makefile on Linux which builds several HDK SOP operators into a single plugin library named StudioSOPs.so:

# Installation directory.
INSTDIR = $(HOME)/houdiniX.Y
# List of C++ source files to build.
# SOP_Main.C registers the operators and handles the DSO-specifics.
./SOP_Main.C \
./Generators/SOP_Cone.C \
./Generators/SOP_Wave.C \
./Modifiers/SOP_Cut.C \
# Icons for custom node operators.
SOP_cone.svg \ SOP_wave.svg \ SOP_cut.svg \ SOP_bend.svg
# Use the highest optimization level.
# Additional include directories.
-I/opt/studio/sdk/include \
# Additional library directories.
-L/opt/studio/sdk/lib \
# Additional libraries.
LIBS = \
-lstudioSDK \
# Set the plugin library name.
DSONAME = StudioSOPs.so
# Include the GNU Makefile.
include $(HFS)/toolkit/makefiles/Makefile.gnu

Now to build your plugin library, go to the directory containing your Makefile and type:

# The make target is DSONAME.
# Similarly for standalone applications, the target is APPNAME.
make StudioSOPs.so
  • On Windows, remember to set MSVCDir to point to your Microsoft Visual Studio C++ installation before running make or nmake.
  • The Makefile installs your plugin library into the current directory. You still need to copy it to $HOME/houdiniX.Y/dso in order for Houdini to load it.

Compiling with CMake

CMake is a meta-build system that can generate project files for various build systems and IDE's (such as Make, Visual Studio, and Ninja). This documentation describes how to build HDK code with CMake. CMake's documentation should be referenced for anything that is not Houdini-specific.

A CMake configuration file (HoudiniConfig.cmake) is provided in $HFS/toolkit/cmake, which defines an imported library target named Houdini.

For a simple library, an example CMakeLists.txt would be:

# Specify the minimum required version of CMake to build the project.
cmake_minimum_required( VERSION 3.6 )
project( My_HDK_Project )
# Locate Houdini's libraries and header files.
# Registers an imported library target named 'Houdini'.
find_package( Houdini REQUIRED )
# Add a library with two source files.
set( library_name SOP_Star )
add_library( ${library_name} SHARED
# Link against the Houdini libraries, and add required include directories and compile definitions.
target_link_libraries( ${library_name} Houdini )
# Configure several common target properties, such as its output directory.
houdini_configure_target( ${library_name} )

Locating Houdini

In order for find_package(Houdini) to succeed, the toolkit/cmake subdirectory of the Houdini installation you are building against must be in CMAKE_PREFIX_PATH.

There are several ways to specify this path when running CMake:

  • When running CMake from the command line, add the argument -DCMAKE_PREFIX_PATH=/path/to/hfs/toolkit/cmake.
  • If you are using CMake's GUI, use the Add Entry button to set a string cache entry for the value of CMAKE_PREFIX_PATH.
  • Set the CMAKE_PREFIX_PATH environment variable before running CMake.

CMAKE_PREFIX_PATH can also be extended in CMakeLists.txt, before the find_package() call. This can be useful if you require custom logic for determining the path to the Houdini installation (such as inspecting environment variables):

list( APPEND CMAKE_PREFIX_PATH "$ENV{HFS}/toolkit/cmake" )

Running CMake (Command Line)

First, create a separate directory that will contain all generated files (such as the generated build system, object files, etc). One convention is to create a subdirectory named build in the folder containing the root CMakeLists.txt

cd /path/to/src
mkdir build
cd build

From the build directory, run cmake and provide the path to the source directory as an argument. If you followed the above steps, the source directory will be the parent directory.

cmake ..

After running CMake, you are then able to use the generated build system files to compile your code.

  • When using the Unix Makefiles or Ninja generators, simply run make or ninja, respectively, in the build directory.
  • For IDE's, a project file (such as a .sln file for Visual Studio) will have been generated in the build directory.

There are also many optional arguments that can be provided to control CMake's behavior. Some common arguments are:

  • -G <generator>

    Specifies which build system generator to use. If not specified, the default for your platform will be used (such as "Unix Makefiles" for Linux). Some common options are "Unix Makefiles", "Ninja", "Xcode", and "Visual Studio 14 2017 Win64". Running cmake –help will provide a full list of the supported generators for your system.

  • -DCMAKE_BUILD_TYPE=<build_type>

    Specifies the build type (such as "Debug", "Release", or "RelWithDebInfo") for single-configuration generators such as Make or Ninja. For IDEs such as Visual Studio, the IDE settings can be used to select the desired build type.

See CMake's documentation for more information on running CMake.

Variable Reference

The following variables are defined when Houdini is found:

Variable Description
Houdini_FOUND Boolean indicating whether Houdini was found successfully.
Houdini_VERSION String containing the version of Houdini that is being built against.
Houdini_VERSION_MAJOR The major version component of ${Houdini_VERSION}. For version 16.5.123, this is 16.
Houdini_VERSION_MINOR The minor version component of ${Houdini_VERSION}. For version 16.5.123, this is 5.
Houdini_VERSION_PATCH The build version component of ${Houdini_VERSION}. For version 16.5.123, this is 123.

Function Reference

The following functions are available when Houdini is found:

  • houdini_configure_target( target_name [INSTDIR dir] [TAGINFO str] [LIB_PREFIX prefix] )

    Configures several common properties of the specified target:

    • INSTDIR: Specifies a custom output directory for the library or executable.
    • LIB_PREFIX: Specifies a prefix for the library name. The default behavior is to use an empty prefix (e.g. SOP_Star.so instead of libSOP_Star.so).
    • TAGINFO: Additional information to embed in the DSO (for use with sesitag).
  • houdini_get_default_install_dir( <VAR> )

    Returns the default installation directory for the platform (for example, $HOME/houdiniX.Y). This can be used for installing additional files such as documentation and HDAs.

  • houdini_generate_proto_headers( OUTPUT_VAR generated_headers FILES file ... )

    Performs code generation for source files that specify their parameter interface with an embedded DS file.

Custom Allocators

Houdini is built with special custom allocator libraries that override the default allocation routines (eg. malloc, free, etc.). As such any code you build or link into HDK plugins cannot use their own such libraries such as tbbmalloc_proxy. If you do, then conflicts and crashes can occur as a result.