This post is a follow-up on the previous post here.

Installing Eclipse & Pydev

Note: On Windows: depending on whether you are on a 64 or 32
bit machine, make sure you install the correct version of Java and Eclipse.

• Install Java on your
  machine if it isn’t yet done http://www.java.com/
  http://www.java.com/en/download/ie_manual.jsp?locale=en&host=www.java.com:80

• Go to http://www.eclipse.org/downloads/ and then click ‘Eclipse Packages'

  Choose any of the last ‘Packages’ version. It is not really important which one you download, could be the Java, Classic or C++ -it does not yet matter. Personally, I have chosen the C/C++ package and combined it later with the Java and PHP packages. These packages are ZIP files, so you can uncompress them on top of a previous one if you want.
  Once installed, Start Eclipse and choose a workspace folder (your favorite place for Maya Python projects).

• After Eclipse have fully started, go into -> Help -> Install New Softwares
  Click on the ‘Add…’ button and fill the form with ‘Name=PyDev – Location=http://pydev.org/updates’
• After you accepted the EULA and legal stuff, this should bring PyDev and PyDev Mylyn Integration (optional) into the list. Select them to install them.
• Restart Eclipse

You are almost ready!

Configuring Eclipse

You only need to do this section if you wish to execute a standard Python application or a Maya Standalone application. If you only want to debug Maya Python scripts and Maya plug-ins, feel free to skip these steps.

• Start Eclipse
• Go into -> Window -> Preferences
• Go into -> PyDev -> Interpreter – Python
  • Python Interpreters -> New…
    • Interpreter Name = Python Maya
    • Interpreter Executable = ‘C:\Program Files\Autodesk\Maya2013\bin\mayapy.exe’
• Accept all proposed path and include both paths below
  • ‘C:\Program Files\Eclipse\plugins\org.python.pydev_2.6.0.2012062818\pysrc’
  • ‘C:\Program Files\Autodesk\Maya2013\bin\python26.zip’

If you also want to configure another interpreter for a standard Python application and have Python installed already, do so now by adding a second interpreter configuration. You can add as many as you want.

Note the '2.6.0.2012062818' key in red above is changing depending of the Pydev version and it is important that you update it if you using a different version in future.

Preparing
debugger scripts for Maya

• Copy the attached Python script (debugmaya.py) into ‘C:\Users\<my profile>\Documents\maya\scripts’

  IMPORTANT: Modify the path in the .py script to reflect the location where you have installed Eclipse (see line #18)

• Copy the attached MEL script (scriptEditorPanel.mel) into ‘C:\Users\<profile>\Documents\maya\2013-x64\prefs\scripts’
• Copy the attached image (debug.png) into ‘C:\Users\<profile>\Documents\maya\2013-x64\prefs\icons’

You are now ready! You can start Maya

NOTE: The paths mentioned above are for a Windows 64 bit machine. If you are running on a win32 machine, please adjust the path accordingly.

NOTE: For other platforms, the procedure is the same excepted for the paths mentioned above.

Let’s debug now

First be aware that you can debug
both Maya Python scripts, Maya Python API plug-ins, and PyMel scripts, running
inside Maya or in standalone mode.

Standalone
application

• Start Eclipse
• Create a new project
  -> File -> New -> Pydev Project (if you can’t see it, then go to ->
  File -> New -> Project… then expand the Pydev folder, select ‘Pydev
  Project’, and click ‘Next’)
  • Give a ‘Project name’
  • Select
    • Project type = Python
    • Grammar Version = 2.6
    • Interpreter  = Python Maya
  • Note: If you get
    the ‘Open Associated Perspective?’ dialogue box, choose ‘Yes’
  • Finish
• Expand your project
  node in the Pydev Package Explorer window
• Select the ‘src’
  node, right-click -> New -> Pydev Module
  • Give a ‘Name’ to your file (no extension)
  • Select Template = ‘Module: Main’
  • Finish
• Modify the code to
  do something using Maya
  • Use the helloworld.py sample from ‘C:\Program
    Files\Autodesk\Maya2013\devkit\applications\scripted’

You
are ready to run or debug your code now

Note: There is nothing different to debug a standard Python
application here. Whether you continue using the mayapy.exe or you switch to
another interpreter. Eclipse can manage several Run/Debug configurations. See
Eclipse documentation for more details.

Maya
Python script (and PyMel)

This
time it is a bit more complicated. Since Maya scripts are running inside Maya,
we cannot launch mayapy.exe and expect to see maya.exe executing our script.
Instead, we need to use the remote debugging feature of Eclipse/PyDev. What is
Remote Debugging? In theory this feature is made to debug Python application
running on a different machine than yours. While it is possible to do this as
well with Maya Python, we are only interested to run it on the same machine at
this time. This is to simplify the configuration. However, remember you can
debug a script running in a Maya session running on another machine than yours.
How cool is that? ;)

Anyway,
let’s rock into our local debug Maya script debug session now. First, you
remember how we had to install a script called ‘debugmaya.py’ during install time;
this script will be used to connect Maya to the Eclipse Python remote debugger
server. This script will ‘alert’ Eclipse that someone is executing some Python
code and that we want to pass control to the Eclipse debugger. How to do this?

• In Eclipse, switch
  to the debug perspective
  (see -> Window -> Open Perspective -> Others… if you haven’t
  configured your favorites yet)
• You should now see 2
  buttons in the Eclipse toolbar:

A red square P button with a tooltip saying ‘Pydev: stop the debugger server’
A green bug P button with a tooltip saying ‘Pydev: start the pydev server’

• Click on the ‘green
  bug P’ button
  • On the ‘Console’ panel, you should now read ‘Debug Server at
    port: 5678’
  • You should also see a debugger instance in the ‘Debug’
    panel
• Now the remote
  debugger is started, you can now start Maya
• Open the Maya Script
  Editor and select a Python tab and write the following code as an example (or
  any code you’d like to debug)
  • import
    sys
  • print
    sys.path
• Launch the debugger
  using the new ‘Debug’ button in the Script Editor (near the ‘Execute All’
  button)
  
  If
  everything was configured properly, you should see a few lines of text
  displayed in the Maya history pane, after that it looks like Maya has frozen
  but don’t panic, switch to Eclipse and see that Eclipse is pausing on a line
  saying:
  • pydevd.settrace()
  • This is the ‘alert’ signal from the remote application to
    the debugger. This leaves you a chance to prepare your debugging session before
    any code is executed. For example, you can set breakpoints in your code.
• However, if you pay
  attention to the Maya history pane and the debugger panel, you’ll notice that
  the Pydev debugger tells you two things:
  • Pydev debugger – <module> [<maya console>:NN]
  • Maya console – “#
    pydev debugger: Unable to find real location for: <maya console>”

  This
  is because the code which is in the Maya Script Editor has no physical file,
  and Pydev needs a file to retrieve the code for the debugger.

• Go into your
  ‘C:\Users\<profile>\Documents\maya\2013-x64\scripts’, you should find a
  file named ‘__debug.py’. Drag and drop it into Eclipse. You should see the code
  you put into your Maya Python tab in the Script Editor. Now, in the left grayed
  margin either dbl-click or right-click to add a breakpoint on the print
  statement and press F8 to resume execution. The debugger should now stop right
  there, and now you have full access to your Maya/Python environments for
  debugging purposes.

You
can now debug a Maya script as well as a PyMel script.

Maya
Python plug-ins

Almost
the same as a ‘Python Script’, the only differences are:

• You load/unload
  plug-ins as any other plug-ins
• You need to modify
  your plug-in script and add 2 lines at the top of the file

import debugmaya
debugmaya.startDebug()

If
your debugger is already started, skip the next 3 steps and go directly into
Maya

• In Eclipse, switch
  to the debug perspective
  (see -> Window -> Open Perspective -> Others… if you haven’t
  configured your favorites yet)
• You should now see 2
  buttons in the Eclipse toolbar:

A red square P button with a tooltip saying ‘Pydev: stop the debugger server’
A green bug P button with a tooltip saying ‘Pydev: start the pydev server’

• Click on the ‘green
  bug P’ button
  • On the ‘Console’ panel, you should now read ‘Debug Server at port: 5678’
  • You should also see a debugger instance in the ‘Debug’
    panel
• Now the remote
  debugger is started, you can now start Maya
• Go into the Plug-in
  Manager and load your Python scripted plug-in (I used the sineNode.py sample
  from the devkit folder)
• Switch to Eclipse
  and see that Eclipse is pausing on the same line we described in the previous
  chapter.
• Load your plug-in
  code into Eclipse and put breakpoints in initializePlugin() and in the
  sineNode.__init__() function. Press F8 to resume.
  The
  debugger should stop immediately into initializePlugin() at the position you
  set the breakpoint. Press F8 again to resume execution.
  Open
  the Script Editor, and in a MEL tab execute the following code

createNode “spSineNode”

The debugger should stop into sineNode.__init__()
at the position you set the breakpoint. Press F8 again to resume execution.

• In the Plug-in
  Manager, unload and load the Python scripted plug-in again, and see the
  debugger stopping again and again at your breakpoints

You can now debug Maya scripted plug-ins.

Advanced concepts

import
& reload()

One
important concept in Python is that import is executed only once. If you modify
your code, you need to use the function reload() to force Maya to refresh the
code changes. The debugmaya.py comes with an ImporterController which will take
care of cleaning your Python environment so you do not have to care about this
at all. However, you should be aware of what is done in the background. When
you load a Python module, Python keeps an internal reference in a dictionary to
avoid having to reload the same file definition multiple time. While it is good
for performance and cross references, it is a disaster for someone who wants to
debug the code, because it would mean to restart the application each time. To
avoid this problem, the debugger creates a singleton instance of the controller
and the controller makes a copy of the references dictionary. Then it replaces
the built-in import function. From there any new imported modules would be
reloaded each time when requested, but not the ones which were already loaded
before the debugger started.

Debugging Python Maya native files

All
Python Maya native files are zipped in the Python26.zip file. If you want to
step through that code you need to either modify PyDev to extract the file on
the fly, or you may explode Python26.zip file in
‘C:\Users\<profile>\Documents\maya\2013-x64\scripts’. Both solution will
work. But I do recommend to do this only when you need to debug Python native
files and only temporarily. 

Will I be able to
step-in Maya Python function and API?

No, you can only step
through your own code. Maya functions and API are almost all written in C/C++.
Unless a Maya component was written in Python language and exposed in a
physical file, you wouldn’t be able to step through that code.

Can
this solution be used in previous releases of Maya?

Yes,
absolutely. All Maya versions with Python support can use this technique and add debugging support to Python. That includes releases starting from Maya 8.5.