Using Wing with NUKE and NUKEX

Index of All Documentation » How-Tos » How-Tos for Modeling, Rendering, and Compositing Systems »

Wing is a Python IDE that can be used to develop, test, and debug Python code written for The Foundry's NUKE and NUKEX digital compositing tool. Two versions of Wing are appropriate for use with this document: Wing Pro is the full-featured Python IDE for professional programmers, and Wing Personal is a free alternative with reduced feature set.

If you do not already have Wing installed, download it now.

To get started using Wing, refer to the tutorial in the Help menu in Wing or the Quickstart Guide.

Project Configuration

First, launch Wing and create a new project from the Project menu and save it to disk. Files can be added to the project with the Project menu. This is not a requirement for working with NUKE but recommended so that Wing's source analysis, search, and revision control features know which files are part of the project.

Next, make sure Wing is using NUKE's Python installation, or a Python that matches NUKE's Python version.

Configuring for Licensed NUKE/NUKEX

If you have NUKE or NUKEX licensed and are not using the Personal Learning Edition, then you can create a script to run NUKE's Python in terminal mode and use that as the Python Executable in Wing's Project Properties. For example on OS X create a script like this:

/Applications/Nuke6.3v8/ -t -i "$@"

Then perform chmod +x on this script to make it executable. On Windows, you can create a batch file like this:

@echo off
"c:\Program Files\Nuke7.0v9\Nuke7.0.exe" -t -i %*

Next, you will make the following changes in Project Properties, from the Project menu in Wing:

  • Set Python Executable to point to this script
  • Change Python Options under the Debug tab to Custom with a blank entry area (no options instead of -u)

Apply these changes and Wing will use NUKE's Python in its Python Shell (after restarting from its Options menu), for debugging, and for source analysis.

Configuring for Personal Learning Edition of NUKE

The above will not work in the Personal Learning Edition of NUKE because it does not support terminal mode. In that case, install a Python version that matches NUKE's Python and use that instead. You can determine the correct version to use by by looking at sys.version in NUKE's Script Editor. Then point Wing to that Python with Python Executable in Project Properties. Using a matching Python version is a good idea to avoid confusion caused by differences in Python versions, but is not critical for Wing to function. However, Wing must be able to find some Python version or many of its features will be disabled.

Additional Project Configuration

When using Personal Learning Edition, and possibly in other cases, some additional configuration is needed to obtain auto-completion on the NUKE API also when the debugger is not connected or not paused. The API is located inside the NUKE installation, in the plugins directory. The plugins directory (parent directory of the nuke package directory) should be added to the Python Path configured in Wing's Project Properties (as accessed from the Project menu). On OS X this directory is within the NUKE application bundle, for example /Applications/Nuke6.3v8/

Replacing the NUKE Script Editor with Wing Pro

Wing Pro can be used as a full-featured Python IDE to replace NUKE's Script Editor component. This is done by downloading and configuring NukeExternalControl.

First set up and test the client/server connection as described in the documentation for NukeExternalControl. Once this works, create a Python source file that contains the necessary client-side setup code and save this to disk.

Next, set a breakpoint in the code after the NUKE connection has been made, by clicking on the breakpoint margin on the left in Wing's editor or by clicking on the line and using Add Breakpoint in the Debug menu or the breakpoint icon in the toolbar.

Then debug the file in Wing Pro by pressing the green run icon in the toolbar or with Start/Continue in the Debug menu. After reaching the breakpoint, use the Debug Probe in Wing to work interactively in that context.

You can also work on a source file in Wing's editor and evaluate selections within the file in the Debug Probe, by right-clicking on the editor.

Both the Debug Probe and Wing's editor should offer auto-completion on the NUKE API, at least while the debugger is active and paused in code that is being edited. The Source Assistant in Wing Pro provides additional information for symbols in the auto-completer, editor, and other tools in Wing.

This technique will not work in Wing Personal because it lacks the Debug Probe feature. However, debugging is still possible using the alternate method described in the next section.

Debugging Python Running Under NUKE

Another way to work with Wing and NUKE is to connect Wing directly to the Python instance running under NUKE. In order to do this, you need to import a special module in your code, as follows:

import wingdbstub

You will need to copy out of the install directory listed in Wing's About box and may need to set WINGHOME inside to the location where Wing is installed if this value is not already set by the Wing installer. On OS X, WINGHOME should be set to the full path of Wing's .app folder.

Before debugging will work within NUKE, you must also set the kEmbedded flag inside to 1.

Next click on the bug icon in the lower left of Wing's main window and make sure that Accept Debug Connections is checked.

Then execute the code that imports the debugger. For example, right click on one of NUKE's tool tabs and select Script Editor. Then in the bottom panel of the Script Editor enter import wingstub and press the Run button in NUKE's Script Editor tool area. You should see the bug icon in the lower left of Wing's window turn green, indicating that the debugger is connected.

If the import fails to find the module, you may need to add to the Python Path as follows:

import sys
import wingdbstub

After that, breakpoints set in Python modules should be reached and Wing's debugger can be used to inspect, step through code, and try out new code in the live runtime. Breakpoints set in the script itself won't be hit, though, due to how Nuke loads the script so code to be debugged should be put in modules that are imported.

For example, place the following code in a module named that is located in the same directory as or anywhere on the sys.path used by NUKE:

def wingtest():
  import nuke

Then set a breakpoint on the line import nuke by clicking in the breakpoint margin to the left, in Wing's editor.

Next enter the following and press the Run button in NUKE's Script Editor (just as you did when importing wingdbstub above):

import testnuke

As soon as the second line is executed, Wing should reach the breakpoint. Then try looking around with the Stack Data and Debug Probe (in Wing Pro only).

Debugger Configuration Detail

If the debugger import is placed into a script file, you may also want to call Ensure on the debugger, which will make sure that the debugger is active and connected:

import wingdbstub

This way it will work even after the Stop icon has been pressed in Wing, or if Wing is restarted or the debugger connection is lost for any other reason.

For additional details on configuring the debugger see Debugging Externally Launched Code.

Limitations and Notes

When Wing's debugger is connected directly to NUKE and at a breakpoint or exception, NUKE's GUI will become unresponsive because NUKE scripts are run in a way that prevents the main GUI loop from continuing while the script is paused by the debugger. To regain access to the GUI, continue the paused script or disconnect from the debug process with the Stop icon in Wing's toolbar.

NUKE will also not update its UI to reflect changes made when stepping through a script or otherwise executing code line by line. For example, typing import nuke; nuke.createNode('Blur') in the Debug Probe will cause creation of a node but NUKE's GUI will not update until the script is continued.

When the NUKE debug process is connected to the IDE but not paused, setting a breakpoint in Wing will display the breakpoint as a red line rather than a red dot during the time where it has not yet been confirmed by the debugger. This can be any length of time, if NUKE is not executing any Python code. Once Python code is executed, the breakpoint should be confirmed and will be reached. This delay in confirming the breakpoint does not occur if the breakpoint is set while the debug process is already paused, or before the debug connection is made.

These problems should only occur when Wing's debugger is attached directly to NUKE, and can be avoided by working through NukeExternalControl instead, as described in the first part of this document.

Related Documents

Wing provides many other options and tools. For more information: