<type>how-to</type>
<domain>install</domain>
<id>nuke</id>
<title>Using Wing with NUKE and NUKEX</title>
<date>$Date: 2006-12-28 17:21:05 -0500 (Thu, 28 Dec 2006) $</date>
<product>pro+</product>
<summary>Learn how to use Wing Pro to develop Python code written for the The Foundry's NUKE and NUKEX digital compositing tools.</summary>

.. image:: /images/screenshots/wing7-screenshot-dark.png
  :alt: Wing Screen Shot
  :width: 574
  :height: 423
  :popup: 1

`Wing Pro <https://wingware.com>`__ is a Python IDE that can be used to develop, test, and
debug Python code written for
The Foundry's `NUKE and NUKEX <http://www.thefoundry.co.uk/products/nuke/>`__
digital compositing tool. 

If you do not already have Wing Pro installed, `download it now <https://wingware.com/downloads/wingpro>`__.

This document describes how to configure Wing for NUKE and NUKEX. To get started using
Wing as your Python IDE, please refer to the tutorial in Wing's ``Help`` menu or read the
`Quickstart Guide <ref:howtos/quickstart>`__.

Project Configuration
---------------------

First, launch Wing and create a new project from the ``Project`` menu.  Although not
required for working with NUKE, you may want to select your existing source directory
or add it after project creation with ``Add Existing Directory`` in the ``Project`` menu.
Doing this tells Wing's source analysis, search, and revision control features know which
files are part of the project.

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 macOS create a script like this::

  #!/bin/sh
  /Applications/Nuke6.3v8/Nuke6.3v8.app/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 ``Command Line`` and then enter the full path 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 set ``Python Executable`` in ``Project Properties``, from the ``Project`` menu in
Wing, to the full path to the Python interpreter. The correct value to use can be
determined by running Python outside of Wing and executing the following:

.. python::

  import sys
  print(sys.executable)

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`` from the ``Project``
menu. On macOS this directory is within the NUKE application bundle, for example
``/Applications/Nuke6.3v8/Nuke6.3v8.app/Contents/MacOS/plugins``.

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
<https://github.com/Nvizible/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
Console`` 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 Console`` with ``Evaluate Selection in Debug Console`` from the ``Source``
menu.

Both the ``Debug Console`` 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 Console``
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:

.. python::

  import wingdbstub
  
You will need to copy ``wingdbstub.py`` out of the install directory listed in Wing's
`About <script:about-application>`__ box and may need to set ``WINGHOME`` inside
``wingdbstub.py`` to the location where Wing is installed if this value is not already set
by the Wing installer. On macOS, ``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
``wingdbstub.py`` 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:

.. python::

  import sys
  sys.path.append("/path/to/wingdbstub")
  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 ``testnuke.py`` that is located in
the same directory as ``wingdbstub.py`` or anywhere on the ``sys.path`` used by NUKE:

.. python::

  def wingtest():
    import nuke
    nuke.createNode('Blur')
  
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:

.. python::

  import testnuke
  testnuke.wingtest()
  
As soon as the second line is executed, Wing should reach the breakpoint. Then try looking
around with the ``Stack Data`` and ``Debug Console`` (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:

.. python::

  import wingdbstub
  wingdbstub.Ensure()
  
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
<ref:debug/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 Console`` 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
-----------------

For more information see:

* `NUKE/NUKEX home page <http://www.thefoundry.co.uk/products/nuke/>`__, 
  which provides links to documentation.

* `Quickstart Guide <ref:howtos/quickstart>`__ contains additional basic information
  about getting started with Wing.
  
* `Tutorial <ref:intro/tutorial>`__ provides a gentler introduction to Wing's features.

* `Wing Reference Manual <ref:manual>`__ documents Wing in detail.
